From 87719ebdd3d71e7883e7c45d72908429bfea86c9 Mon Sep 17 00:00:00 2001 From: m1ngsama Date: Sat, 23 May 2026 18:15:41 +0800 Subject: [PATCH] Add in-editor beta guide --- .vimrc | 1 + BETA.md | 9 +++ QUICKSTART.md | 3 + README.md | 11 +++- modules/beta.vim | 122 +++++++++++++++++++++++++++++++++++++++++ modules/cheatsheet.vim | 6 ++ modules/status.vim | 22 ++++++++ modules/tutor.vim | 6 ++ scripts/test-vim.sh | 47 ++++++++++++++++ 9 files changed, 226 insertions(+), 1 deletion(-) create mode 100644 modules/beta.vim diff --git a/.vimrc b/.vimrc index 06ee093..806a41a 100644 --- a/.vimrc +++ b/.vimrc @@ -37,4 +37,5 @@ call s:load('quickfix') call s:load('status') call s:load('cheatsheet') call s:load('tutor') +call s:load('beta') call s:load('tools') diff --git a/BETA.md b/BETA.md index 1d21397..052a15e 100644 --- a/BETA.md +++ b/BETA.md @@ -3,6 +3,10 @@ This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0` until the checklist below is closed. +Inside Vim, run `:ChopsticksBeta` for the compact checklist, +`:ChopsticksBetaLog` for editable local notes, and `:ChopsticksBetaSession` +to append a new session block. + ## Install the beta Existing checkout: @@ -40,6 +44,11 @@ Use the beta for real editing, not only demos. For each session, record: - Any mapping that felt slow, awkward, surprising, or too easy to mistype. - Any documentation line that was wrong, missing, or redundant. +`:ChopsticksBetaLog` opens `${XDG_CONFIG_HOME:-~/.config}/chopsticks-beta.md` +by default. Set `g:chopsticks_beta_log` before loading chopsticks to use a +different path. Use `:ChopsticksBetaSession` at the start of each real editing +session so every test has a timestamped block. + ## Workflows to exercise ```text diff --git a/QUICKSTART.md b/QUICKSTART.md index 1a3fc82..b09684b 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -4,6 +4,9 @@ Five minutes from zero to a working Vim setup. ## Install +These commands install the stable `main` branch. For beta testing this branch, +use [BETA.md](BETA.md). + ```bash curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --profile=minimal diff --git a/README.md b/README.md index 32b8a46..1e2e991 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,15 @@ --- +Stable install from `main`: + ```bash curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash ``` This branch is a v3 beta candidate, not a tagged stable release. Use -[BETA.md](BETA.md) when testing the Space keymap before promotion. +[BETA.md](BETA.md) instead of the stable install command when testing the Space +keymap before promotion. --- @@ -71,6 +74,9 @@ chopsticks gives you a production-ready Vim config in one command. Pure VimScrip ## Install +These commands install the stable `main` branch. For beta testing this branch, +use [BETA.md](BETA.md). + ```bash curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --profile=minimal @@ -139,6 +145,8 @@ for native `S`. For onboarding, use `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active keymap, 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 and +`:ChopsticksBetaLog` opens editable local notes. ``` SPC SPC fuzzy find file gd go to definition @@ -293,6 +301,7 @@ For Markdown LSP, install or select `marksman` first. │ ├── status.vim :ChopsticksStatus diagnostics │ ├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet │ ├── tutor.vim :ChopsticksTutor guided practice +│ ├── beta.vim :ChopsticksBeta test guide │ └── tools.vim compatibility placeholder ``` diff --git a/modules/beta.vim b/modules/beta.vim new file mode 100644 index 0000000..90c85b5 --- /dev/null +++ b/modules/beta.vim @@ -0,0 +1,122 @@ +" beta.vim — in-editor beta test guide + +let g:chopsticks_beta_label = get(g:, 'chopsticks_beta_label', '3.0.0-beta.1') + +function! s:OpenBetaGuide() abort + let l:name = '__ChopsticksBeta__' + if bufwinnr(l:name) > 0 + execute bufwinnr(l:name) . 'wincmd w | bd' + return + endif + + execute 'botright new ' . l:name + resize 34 + setlocal buftype=nofile bufhidden=wipe nobuflisted noswapfile + setlocal nowrap nonumber norelativenumber signcolumn=no + + let l:lines = [ + \ ' chopsticks beta q close', + \ ' ─────────────────────────────', + \ '', + \ ' goal', + \ ' Prove the v3 Space layout in real editing before release.', + \ ' Record friction, not opinions in the abstract.', + \ '', + \ ' daily loop', + \ ' SPC SPC find file', + \ ' s + 2ch jump on screen', + \ ' gd / gr definition / references', + \ ' K hover docs', + \ ' SPC / grep project', + \ ' SPC rr run current file', + \ ' SPC gs git status', + \ ' SPC cf format', + \ ' SPC ? active cheat sheet', + \ ' :ChopsticksBetaSession new note block', + \ '', + \ ' record', + \ ' task: project navigation, code, grep, git, LSP, Markdown, SSH', + \ ' first key tried when stuck', + \ ' whether SPC ?, :ChopsticksTutor, or :ChopsticksStatus answered it', + \ ' any key that felt slow, awkward, surprising, or easy to mistype', + \ '', + \ ' exit criteria', + \ ' 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', + \ ' quick/vim tests pass locally and over SSH', + \ '', + \ ' files', + \ ' BETA.md full beta checklist and rollback', + \ ' :ChopsticksBetaLog editable local beta notes', + \ ' :ChopsticksBetaSession append a new session block', + \ ' QUICKSTART.md five-minute path', + \ ' README.md complete reference', + \ ] + + call setline(1, l:lines) + setlocal nomodifiable readonly + nnoremap q :bd + nnoremap ? :ChopsticksCheatSheet +endfunction + +function! s:BetaLogPath() abort + let l:configured = get(g:, 'chopsticks_beta_log', '') + if !empty(l:configured) + return expand(l:configured) + endif + + let l:xdg = !empty($XDG_CONFIG_HOME) && $XDG_CONFIG_HOME =~# '^/' + \ ? $XDG_CONFIG_HOME + \ : '~/.config' + return expand(l:xdg . '/chopsticks-beta.md') +endfunction + +function! s:SessionBlock() abort + return [ + \ '', + \ '## ' . strftime('%Y-%m-%d %H:%M'), + \ '', + \ '- Task:', + \ '- First key tried when stuck:', + \ '- Did SPC ?, :ChopsticksTutor, or :ChopsticksStatus answer it:', + \ '- Friction:', + \ '- Decision:', + \ ] +endfunction + +function! s:EnsureBetaLog(path) abort + let l:path = a:path + let l:dir = fnamemodify(l:path, ':h') + if !isdirectory(l:dir) + call mkdir(l:dir, 'p') + endif + + if !filereadable(l:path) + call writefile([ + \ '# chopsticks beta log', + \ '', + \ 'Use :ChopsticksBeta for the checklist. Keep one session block per real editing session.', + \ ] + s:SessionBlock(), l:path) + endif +endfunction + +function! s:OpenBetaLog() abort + let l:path = s:BetaLogPath() + call s:EnsureBetaLog(l:path) + execute 'edit ' . fnameescape(l:path) + setlocal filetype=markdown +endfunction + +function! s:AppendBetaSession() abort + let l:path = s:BetaLogPath() + call s:EnsureBetaLog(l:path) + call writefile(s:SessionBlock(), l:path, 'a') + execute 'edit ' . fnameescape(l:path) + setlocal filetype=markdown + normal! G +endfunction + +command! ChopsticksBeta call s:OpenBetaGuide() +command! ChopsticksBetaLog call s:OpenBetaLog() +command! ChopsticksBetaSession call s:AppendBetaSession() diff --git a/modules/cheatsheet.vim b/modules/cheatsheet.vim index 1347d54..b341fe0 100644 --- a/modules/cheatsheet.vim +++ b/modules/cheatsheet.vim @@ -149,6 +149,9 @@ function! s:CheatSheet() abort \ ' SPC fV reload vimrc', \ ' :ChopsticksTutor practice', \ ' :ChopsticksStatus health', + \ ' :ChopsticksBeta beta test guide', + \ ' :ChopsticksBetaLog beta notes', + \ ' :ChopsticksBetaSession new beta note', \ ]) call s:OpenCheatSheet(l:lines) @@ -259,6 +262,9 @@ function! s:CheatSheet() abort \ ' ,sv reload vimrc', \ ' :ChopsticksTutor practice', \ ' :ChopsticksStatus health', + \ ' :ChopsticksBeta beta test guide', + \ ' :ChopsticksBetaLog beta notes', + \ ' :ChopsticksBetaSession new beta note', \ ]) call s:OpenCheatSheet(l:lines) diff --git a/modules/status.vim b/modules/status.vim index bafcf06..5c934f9 100644 --- a/modules/status.vim +++ b/modules/status.vim @@ -68,12 +68,34 @@ function! s:LspCheck(ft, server) abort return ' -- ' . a:ft . ' (:LspInstallServer in a ' . a:ft . ' file)' endfunction +function! s:BetaLogPath() abort + let l:configured = get(g:, 'chopsticks_beta_log', '') + if !empty(l:configured) + return expand(l:configured) + endif + + let l:xdg = !empty($XDG_CONFIG_HOME) && $XDG_CONFIG_HOME =~# '^/' + \ ? $XDG_CONFIG_HOME + \ : '~/.config' + return expand(l:xdg . '/chopsticks-beta.md') +endfunction + function! s:ChopsticksStatus() abort let l:lines = [] call add(l:lines, 'chopsticks status') call add(l:lines, repeat('─', 50)) call add(l:lines, '') + if !empty(get(g:, 'chopsticks_beta_label', '')) + call add(l:lines, '── beta ──') + call add(l:lines, ' candidate ' . g:chopsticks_beta_label) + call add(l:lines, ' keymap ' . (get(g:, 'chopsticks_space_keymaps', 0) ? 'space' : 'classic')) + call add(l:lines, ' log ' . s:BetaLogPath()) + call add(l:lines, ' commands :ChopsticksBeta :ChopsticksBetaLog') + call add(l:lines, ' :ChopsticksBetaSession') + call add(l:lines, '') + endif + call add(l:lines, '── system tools ──') call add(l:lines, s:Check('fzf', 'fzf')) call add(l:lines, s:Check('ripgrep', 'rg')) diff --git a/modules/tutor.vim b/modules/tutor.vim index 5d023b9..8ece162 100644 --- a/modules/tutor.vim +++ b/modules/tutor.vim @@ -29,6 +29,9 @@ function! s:ChopsticksTutor() abort \ ' SPC w save', \ ' SPC qx save and quit', \ ' :ChopsticksStatus health check', + \ ' :ChopsticksBeta beta checklist', + \ ' :ChopsticksBetaLog beta notes', + \ ' :ChopsticksBetaSession new note', \ '', \ ' 2. find and switch', \ ' SPC SPC find files', @@ -90,6 +93,9 @@ function! s:ChopsticksTutor() abort \ '', \ ' support', \ ' :ChopsticksStatus health check', + \ ' :ChopsticksBeta beta checklist', + \ ' :ChopsticksBetaLog beta notes', + \ ' :ChopsticksBetaSession new note', \ ' README.md full reference', \ ' QUICKSTART.md 5-minute path', \ ] diff --git a/scripts/test-vim.sh b/scripts/test-vim.sh index 20de91d..467f899 100755 --- a/scripts/test-vim.sh +++ b/scripts/test-vim.sh @@ -79,6 +79,11 @@ check_vim() { exit 1 fi grep -Fq 'OK vim-lsp stack (installed)' "$TMP_ROOT/status-default.txt" + grep -Fq 'candidate 3.0.0-beta.1' "$TMP_ROOT/status-default.txt" + grep -Fq 'keymap space' "$TMP_ROOT/status-default.txt" + grep -Fq 'commands :ChopsticksBeta :ChopsticksBetaLog' "$TMP_ROOT/status-default.txt" + grep -Fq ':ChopsticksBetaSession' "$TMP_ROOT/status-default.txt" + grep -Fq 'chopsticks-beta.md' "$TMP_ROOT/status-default.txt" grep -Fq 'python (:LspInstallServer in a python file)' "$TMP_ROOT/status-default.txt" grep -Fq 'LSP actions are buffer-local and start after a server attaches.' "$TMP_ROOT/status-default.txt" grep -Fq 'Open that filetype and run :LspInstallServer once.' "$TMP_ROOT/status-default.txt" @@ -254,6 +259,9 @@ check_vim() { grep -Fq 's+2ch easymotion jump' "$TMP_ROOT/cheat-default.txt" grep -Fq 'cl / cc native s / S substitute' "$TMP_ROOT/cheat-default.txt" grep -Fq ':ChopsticksTutor practice' "$TMP_ROOT/cheat-default.txt" + grep -Fq ':ChopsticksBeta beta test guide' "$TMP_ROOT/cheat-default.txt" + grep -Fq ':ChopsticksBetaLog beta notes' "$TMP_ROOT/cheat-default.txt" + grep -Fq ':ChopsticksBetaSession new beta note' "$TMP_ROOT/cheat-default.txt" if grep -Eq 'Ctrl\\+p find file|Ctrl\\+hjkl navigate splits|Ctrl\\+s save|jk exit insert|SPC fs save|SPC cd definition|SPC ck hover|SPC wm|SPC w\\+/-|\\[g \\]g LSP diagnostics' "$TMP_ROOT/cheat-default.txt"; then cat "$TMP_ROOT/cheat-default.txt" exit 1 @@ -340,6 +348,45 @@ check_vim() { grep -Fq ',? active cheat sheet' "$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 "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 '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" + grep -Fq ':ChopsticksBetaSession append a new session block' "$TMP_ROOT/beta-guide.txt" + + beta_log="$TMP_ROOT/beta log/chopsticks-beta.md" + XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \ + -c "let g:chopsticks_beta_log = '$beta_log'" \ + -c 'source .vimrc' \ + -c 'ChopsticksBetaLog' \ + -c 'if expand("%:p") !~# "chopsticks-beta.md" || &l:filetype !=# "markdown" | cquit | endif' \ + -c 'qa!' 2>&1 + grep -Fq '# chopsticks beta log' "$beta_log" + grep -Fq 'First key tried when stuck:' "$beta_log" + printf '%s\n' '- keep-existing-note' >> "$beta_log" + XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \ + -c "let g:chopsticks_beta_log = '$beta_log'" \ + -c 'source .vimrc' \ + -c 'ChopsticksBetaLog' \ + -c 'qa!' 2>&1 + grep -Fq -- '- keep-existing-note' "$beta_log" + before_sessions="$(grep -c '^## ' "$beta_log")" + XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \ + -c "let g:chopsticks_beta_log = '$beta_log'" \ + -c 'source .vimrc' \ + -c 'ChopsticksBetaSession' \ + -c 'qa!' 2>&1 + after_sessions="$(grep -c '^## ' "$beta_log")" + test "$after_sessions" -eq $((before_sessions + 1)) + grep -Fq -- '- keep-existing-note' "$beta_log" + XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N README.md \ -c 'let g:chopsticks_keymap_style = "space"' \ -c 'source .vimrc' \