diff --git a/.github/demo.gif b/.github/demo.gif index 8b71919..9e395e9 100644 Binary files a/.github/demo.gif and b/.github/demo.gif differ diff --git a/.github/demo.tape b/.github/demo.tape index 7e6a8e5..bca3f76 100644 --- a/.github/demo.tape +++ b/.github/demo.tape @@ -1,5 +1,6 @@ -# chopsticks demo — the project loop stock Vim does not assemble for you: -# visible jump → file finder → run file → project grep → active key help. +# chopsticks demo — for people who already know Vim: +# show the project workflow layer Vim does not assemble by default. +# project loop: visible jump → files → run → grep → git → active key help. # Rule: NEVER use Escape to close FZF — always Enter (deterministic). # Pacing: hold each scene long enough for the viewer to read. @@ -30,15 +31,18 @@ Type "cd $CHOPSTICKS_DEMO_PROJECT" Enter Type "git init -q && git symbolic-ref HEAD refs/heads/main && git add ." Enter +Type `clear && printf "%s\n" "chopsticks: a long-term Vim efficiency kit" "" "For experienced Vim users who already know how to edit." "Keep Vim's language. Standardize the project loop:" "" " s + 2 chars visible jump on the current screen" " SPC SPC project-aware file switcher" " SPC rr run the current file" " SPC / ripgrep the project" " SPC gs git status, with no push/pull hotkeys" " SPC ? active keys explained inside Vim"` +Enter +Show +Sleep 6s Type "clear" Enter Type `vim -Nu "$CHOPSTICKS_ROOT/.vimrc" server.py` Enter Wait+Screen /server.py/ -Show Sleep 1s -# ── 1. Pain: moving inside a dense screen should not mean counting hjkl ──── +# ── 1. Screen-local motion: stop counting hjkl across dense code ─────────── Type "s" Sleep 0.5s Type "di" @@ -46,7 +50,7 @@ Sleep 2s Ctrl+C Sleep 1s -# ── 2. Pain: project files should be one habit, not :find/:edit plumbing ─── +# ── 2. Project files: one habit for git-aware file switching ─────────────── Space 2 Sleep 1.5s Type "report" @@ -54,14 +58,14 @@ Sleep 2s Enter Sleep 3s -# ── 3. Pain: edit→run should be one repeatable project loop ──────────────── +# ── 3. Edit-run loop: run the current file without leaving Vim ───────────── Space Type "rr" Sleep 4s Enter Sleep 1s -# ── 4. Pain: project search should not leave Vim or require remembering rg ─ +# ── 4. Project grep: ripgrep as part of the same muscle-memory layer ─────── Space Type "/" Sleep 1s @@ -70,7 +74,15 @@ Sleep 2.5s Enter Sleep 3s -# ── 5. Pain: custom keymaps must explain themselves in the editor ────────── +# ── 5. Git boundary: status is fast; push/pull stay explicit commands ────── +Space +Type "gs" +Sleep 3s +Type ":bd!" +Enter +Sleep 1s + +# ── 6. Self-documenting config: no private wiki required ─────────────────── Space Type "?" Sleep 5.5s diff --git a/BETA.md b/BETA.md index fd32895..1f4df0a 100644 --- a/BETA.md +++ b/BETA.md @@ -1,6 +1,8 @@ # Beta Testing -This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0` +This branch is the v3 beta candidate. The goal is to prove that the Space +layout can serve as a long-term project loop for experienced Vim users, not +just that the mappings work in isolation. Do not tag or publish it as `v3.0.0` until the checklist below is closed. Inside Vim, run `:ChopsticksBeta` for the compact checklist, @@ -40,7 +42,9 @@ reloads chopsticks after saving it. ## Daily test loop -Use the beta for real editing, not only demos. For each session, record: +Use the beta for real editing, not only demos. A session should exercise the +trained loop until it either feels automatic or exposes friction. For each +session, record: - The task: project navigation, code edit, grep, git, LSP, Markdown, SSH. - The first key you tried when you got stuck. @@ -74,6 +78,7 @@ file, edit Markdown, and use a machine with missing optional tools. - No high-frequency action requires remembering an undocumented key. - README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor` teach the same layout. +- No private wiki or external note is needed to remember the daily loop. - `scripts/test.sh quick` and `scripts/test.sh vim` pass locally. - The README GIF has been regenerated from `.github/demo.tape` after any public key change. diff --git a/QUICKSTART.md b/QUICKSTART.md index 30edaf9..bb0db9a 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,6 +1,11 @@ # Quick Start -Five minutes from zero to a working Vim setup. +Five minutes to understand the chopsticks project loop. + +This guide assumes you already know Vim's editing language. chopsticks keeps +that language intact and gives you one stable layer for the work around it: +jump on the visible screen, switch project files, grep, run, inspect code, +check git, and ask Vim which keys are active. ## Install @@ -35,13 +40,20 @@ To switch later without reinstalling anything: cd ~/.vim && ./install.sh --configure-only --profile=full ``` -## Modes +## Daily loop -| Mode | Enter | Leave | -| ------ | --------------- | ------------- | -| Normal | startup default | — | -| Insert | `i` / `a` / `o` | `Esc` | -| Visual | `v` / `V` | `Esc` | +Train this first. It is the core reason to use chopsticks instead of assembling +the same pieces yourself: + +``` +SPC SPC open a project file +s + 2 chars jump to visible text +gd / gr / K inspect definition, references, docs +SPC rr run the current file +SPC / grep the project +SPC gs check git status +SPC ? show the active keymap +``` ## Survival diff --git a/README.md b/README.md index 8cd4ea3..490b235 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@

chopsticks demo
- One project loop: jump on screen, find a file, run it, grep the codebase, then ask Vim what keys are active. + For Vim users who already know how to edit: one trained project loop for jump, files, run, grep, git, and active key help.

chopsticks

- A project-work Vim setup: find, jump, run, grep, git, LSP, and self-documenting keys over SSH. + A long-term Vim efficiency kit: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.

@@ -34,7 +34,11 @@ keymap before promotion. ## Why -Stock Vim is a great editor core, but it does not ship a complete project +chopsticks is for experienced Vim users who want one stable, ergonomic working +set they can train once and keep for years. It does not replace Vim's editing +language; it standardizes the project loop around it. + +Stock Vim is a great editor core, but it does not ship that complete project workflow. You still have to assemble fuzzy finding, project grep, git, LSP, diagnostics, formatters, runners, terminal behavior, and a keymap that will not collapse over SSH. @@ -145,10 +149,10 @@ Git push/pull are intentionally not bound to default hotkeys. Normal-mode `s` is a screen-local EasyMotion jump; use `cl` for native `s` substitute and `cc` for native `S`. -For onboarding, use `:ChopsticksHelp` / `:help chopsticks` for full native Vim -help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active -keymap, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus` for -tool/LSP health. +For learning the kit, use `:ChopsticksTutor` to train the core loop, `SPC ?` +for the active keymap, `:ChopsticksHelp` / `:help chopsticks` for full native +Vim help, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus` +for tool/LSP health. `QUICKSTART.md` is the 5-minute path; this README is the full reference. During the beta, `:ChopsticksBeta` opens the in-editor test checklist, `:ChopsticksBetaLog` opens editable local notes, and `:ChopsticksBetaSession` diff --git a/doc/chopsticks.txt b/doc/chopsticks.txt index f2c66b8..fbca7ac 100644 --- a/doc/chopsticks.txt +++ b/doc/chopsticks.txt @@ -1,4 +1,4 @@ -*chopsticks.txt* *chopsticks* A project-work Vim setup +*chopsticks.txt* *chopsticks* A long-term Vim efficiency kit ============================================================================== CONTENTS *chopsticks-contents* @@ -14,9 +14,10 @@ CONTENTS *chopsticks-contents ============================================================================== WHAT CHOPSTICKS SOLVES *chopsticks-why* -Chopsticks is a complete Vim project loop for people who edit locally and over -SSH. It connects fuzzy find, project grep, git, LSP, linting, formatting, -runners, quickfix navigation, and self-documenting keys. +Chopsticks is for experienced Vim users who want one stable, ergonomic working +set they can train once and keep for years. It connects fuzzy find, project +grep, git, LSP, linting, formatting, runners, quickfix navigation, and +self-documenting keys for people who edit locally and over SSH. It is meant to supplement stock Vim, not replace Vim muscle memory. Native motions and well-known conventions stay where they are useful: gd, gr, K, diff --git a/modules/beta.vim b/modules/beta.vim index 90c85b5..d9bb603 100644 --- a/modules/beta.vim +++ b/modules/beta.vim @@ -19,8 +19,8 @@ function! s:OpenBetaGuide() abort \ ' ─────────────────────────────', \ '', \ ' goal', - \ ' Prove the v3 Space layout in real editing before release.', - \ ' Record friction, not opinions in the abstract.', + \ ' Prove this can be a long-term project loop.', + \ ' Record real editing friction, not abstract taste.', \ '', \ ' daily loop', \ ' SPC SPC find file', @@ -44,6 +44,7 @@ function! s:OpenBetaGuide() abort \ ' s as jump still feels worth the native override', \ ' no high-frequency action needs an undocumented key', \ ' README, QUICKSTART, SPC ?, and tutor teach the same layout', + \ ' no private wiki is needed to remember the daily loop', \ ' quick/vim tests pass locally and over SSH', \ '', \ ' files', diff --git a/modules/cheatsheet.vim b/modules/cheatsheet.vim index 5999d4e..39220a7 100644 --- a/modules/cheatsheet.vim +++ b/modules/cheatsheet.vim @@ -29,6 +29,10 @@ function! s:CheatSheet() abort \ ' chopsticks ? close', \ ' ─────────────────────────────────', \ '', + \ ' trained loop:', + \ ' files → s jump → gd/K', + \ ' run → grep → git', + \ '', \ ' ── fast path ─────────────', \ ' SPC SPC files', \ ' SPC , buffers', @@ -166,6 +170,10 @@ function! s:CheatSheet() abort \ ' chopsticks ,? close', \ ' ─────────────────────────────', \ '', + \ ' trained loop:', + \ ' files → jump → inspect', + \ ' run → grep → git', + \ '', \ ' ── files ──────────────────', \ ' ,ff files', \ ' ,b buffers', diff --git a/modules/tutor.vim b/modules/tutor.vim index 0236b98..d427e50 100644 --- a/modules/tutor.vim +++ b/modules/tutor.vim @@ -23,9 +23,20 @@ function! s:ChopsticksTutor() abort \ ' chopsticks tutor q close', \ ' ───────────────────────────────', \ '', - \ ' 1. survival', - \ ' Esc Normal mode', + \ ' Goal: train one long-term project loop around Vim.', + \ ' Keep Vim editing habits; standardize the surrounding work.', + \ '', + \ ' 1. trained loop', + \ ' SPC SPC open a project file', + \ ' s + 2 chars jump to visible text', + \ ' gd / gr / K inspect definition / refs / docs', + \ ' SPC rr run current file', + \ ' SPC / grep project', + \ ' SPC gs check git status', \ ' SPC ? active cheat sheet', + \ '', + \ ' 2. survival', + \ ' Esc Normal mode', \ ' SPC w save', \ ' SPC qx save and quit', \ ' SPC fc edit local config', @@ -38,42 +49,43 @@ function! s:ChopsticksTutor() abort \ ' :ChopsticksBetaLog beta notes', \ ' :ChopsticksBetaSession new note', \ '', - \ ' 2. find and switch', + \ ' 3. find and switch', \ ' SPC SPC find files', \ ' SPC / grep project', \ ' SPC , buffers', \ ' SPC Tab alternate buffer', \ ' SPC e/E sidebar cwd / file dir', \ '', - \ ' 3. jump and edit', + \ ' 4. jump and edit', \ ' s + 2 chars visible jump', \ ' SPC S same jump fallback', \ ' cl / cc native s / S substitute', \ ' gc comment', \ ' SPC U undo tree', \ '', - \ ' 4. code loop', + \ ' 5. code loop', \ ' gd / gr / K definition / refs / docs', \ ' gI / gy implementation / type', \ ' [d ]d LSP diagnostics', \ ' SPC ca/cr/cf action / rename / format', \ ' SPC rr run current file', \ '', - \ ' 5. git and windows', + \ ' 6. git and windows', \ ' SPC gs/gd/gb status / diff / blame', \ ' SPC gl log graph', \ ' hjkl split navigation', \ ' SPC z maximize split', \ '', \ ' daily drill', - \ ' Open a project, run SPC SPC, jump with s, inspect with gd/K,', - \ ' edit with gc/SPC cf, check SPC gs, then save with SPC w.', + \ ' Repeat: SPC SPC, s, gd/K, edit, SPC rr, SPC /, SPC gs.', \ ] else let l:lines = [ \ ' chopsticks tutor q close', \ ' ───────────────────────────────', \ '', + \ ' Goal: train one long-term project loop around Vim.', + \ '', \ ' classic layout', \ ' ,? active cheat sheet', \ ' ,w / ,x save / save and quit', diff --git a/scripts/test-vim.sh b/scripts/test-vim.sh index cf30b58..0c854a7 100755 --- a/scripts/test-vim.sh +++ b/scripts/test-vim.sh @@ -268,11 +268,15 @@ check_vim() { XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \ -c 'call feedkeys("\?", "xt")' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \ -c "redir! > $TMP_ROOT/cheat-default.txt" \ -c 'silent %print' \ -c 'redir END' \ -c 'qa!' 2>&1 grep -Fq ':ChopsticksStatus check LSP setup' "$TMP_ROOT/cheat-default.txt" + grep -Fq 'trained loop:' "$TMP_ROOT/cheat-default.txt" + grep -Fq 'files → s jump → gd/K' "$TMP_ROOT/cheat-default.txt" + grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-default.txt" grep -Fq 'SPC SPC files' "$TMP_ROOT/cheat-default.txt" grep -Fq 'gd definition' "$TMP_ROOT/cheat-default.txt" grep -Fq 'K hover docs' "$TMP_ROOT/cheat-default.txt" @@ -296,6 +300,7 @@ check_vim() { XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \ -c 'ChopsticksCheatSheet' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \ -c "redir! > $TMP_ROOT/cheat-command.txt" \ -c 'silent %print' \ -c 'redir END' \ @@ -307,11 +312,15 @@ check_vim() { -c 'let g:chopsticks_keymap_style = "classic"' \ -c 'source .vimrc' \ -c 'normal ,?' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \ -c "redir! > $TMP_ROOT/cheat-classic.txt" \ -c 'silent %print' \ -c 'redir END' \ -c 'qa!' 2>&1 grep -Fq ',ff files' "$TMP_ROOT/cheat-classic.txt" + grep -Fq 'trained loop:' "$TMP_ROOT/cheat-classic.txt" + grep -Fq 'files → jump → inspect' "$TMP_ROOT/cheat-classic.txt" + grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-classic.txt" grep -Fq ',dd definition' "$TMP_ROOT/cheat-classic.txt" grep -Fq ',dk hover docs' "$TMP_ROOT/cheat-classic.txt" grep -Fq ',dp ,dn LSP diagnostics' "$TMP_ROOT/cheat-classic.txt" @@ -326,6 +335,7 @@ check_vim() { -c 'let g:chopsticks_profile = "minimal"' \ -c 'source .vimrc' \ -c 'call feedkeys("\?", "xt")' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \ -c "redir! > $TMP_ROOT/cheat.txt" \ -c 'silent %print' \ -c 'redir END' \ @@ -340,6 +350,7 @@ check_vim() { -c 'let g:chopsticks_keymap_style = "space"' \ -c 'source .vimrc' \ -c 'call feedkeys("\?", "xt")' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \ -c "redir! > $TMP_ROOT/cheat-space.txt" \ -c 'silent %print' \ -c 'redir END' \ @@ -356,11 +367,14 @@ check_vim() { XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \ -c 'ChopsticksTutor' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \ -c "redir! > $TMP_ROOT/tutor-default.txt" \ -c 'silent %print' \ -c 'redir END' \ -c 'qa!' 2>&1 grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt" + grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-default.txt" + grep -Fq '1. trained loop' "$TMP_ROOT/tutor-default.txt" grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/tutor-default.txt" grep -Fq 'SPC fc edit local config' "$TMP_ROOT/tutor-default.txt" grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/tutor-default.txt" @@ -373,23 +387,28 @@ check_vim() { -c 'let g:chopsticks_keymap_style = "classic"' \ -c 'source .vimrc' \ -c 'ChopsticksTutor' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \ -c "redir! > $TMP_ROOT/tutor-classic.txt" \ -c 'silent %print' \ -c 'redir END' \ -c 'qa!' 2>&1 grep -Fq 'classic layout' "$TMP_ROOT/tutor-classic.txt" + grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-classic.txt" grep -Fq ',? active cheat sheet' "$TMP_ROOT/tutor-classic.txt" grep -Fq ',ec edit local config' "$TMP_ROOT/tutor-classic.txt" grep -Fq ',S + 2 chars EasyMotion jump' "$TMP_ROOT/tutor-classic.txt" XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \ -c 'ChopsticksBeta' \ + -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \ -c "redir! > $TMP_ROOT/beta-guide.txt" \ -c 'silent %print' \ -c 'redir END' \ -c 'qa!' 2>&1 grep -Fq 'chopsticks beta' "$TMP_ROOT/beta-guide.txt" - grep -Fq 'Prove the v3 Space layout in real editing before release.' "$TMP_ROOT/beta-guide.txt" + grep -Fq 'Prove this can be a long-term project loop.' "$TMP_ROOT/beta-guide.txt" + grep -Fq 'Record real editing friction, not abstract taste.' "$TMP_ROOT/beta-guide.txt" + grep -Fq 'no private wiki is needed to remember the daily loop' "$TMP_ROOT/beta-guide.txt" grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/beta-guide.txt" grep -Fq 'BETA.md full beta checklist and rollback' "$TMP_ROOT/beta-guide.txt" grep -Fq ':ChopsticksBetaLog editable local beta notes' "$TMP_ROOT/beta-guide.txt"