feat: initial release

Author: Xiangnong Wu

.github/workflows/docs.yaml

@@ -0,0 +1,31 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'README.md'
+      - '.github/workflows/docs.yaml'
+
+permissions:
+  contents: write
+
+jobs:
+  panvimdoc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Generate vimdoc from README
+        uses: kdheepak/panvimdoc@main
+        with:
+          vimdoc: rubikscube
+          version: "Neovim >= 0.10"
+          pandoc: README.md
+          toc: true
+          treesitter: true
+          demojify: false
+      - name: Commit generated docs
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs: auto-generate vimdoc from README"
+          file_pattern: doc/*.txt

.github/workflows/format.yaml

@@ -0,0 +1,17 @@
+name: format
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  stylua:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JohnnyMorganz/stylua-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          version: latest
+          args: --check .

.github/workflows/lint.yaml

@@ -0,0 +1,16 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  luacheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install luacheck
+        run: sudo apt-get update && sudo apt-get install -y luarocks && sudo luarocks install luacheck
+      - name: Run luacheck
+        run: luacheck lua/ tests/ scripts/ plugin/

.github/workflows/tests.yaml

@@ -0,0 +1,23 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        neovim: [stable, nightly]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: ${{ matrix.neovim }}
+      - name: Run tests
+        run: nvim --headless -l tests/run.lua

.gitignore

@@ -0,0 +1 @@
+.DS_Store

.luacheckrc

@@ -0,0 +1,19 @@
+std = "luajit"
+cache = true
+codes = true
+
+self = false
+
+globals = {
+  "vim",
+}
+
+exclude_files = {
+  "doc/",
+}
+
+-- Tweak strictness for plugin idioms.
+ignore = {
+  "212",  -- unused argument
+  "631",  -- line too long
+}

README.md

@@ -0,0 +1,118 @@
+# rubiks-cube.nvim
+
+A playable Rubik's cube inside Neovim — isometric ASCII render, full move set in Singmaster notation, a timer, and best-time persistence.
+
+![rubiks-cub](assets/rubiks-cub.png)
+
+## Requirements
+
+- Neovim **0.10+** (uses `vim.uv`)
+- `termguicolors` enabled (recommended; falls back to cterm approximations otherwise)
+
+## Installation
+
+### lazy.nvim
+
+```lua
+{
+  "xiangnongWu2233/rubiks-cube.nvim",
+  cmd = "Rubikscube",
+  opts = {},  -- or pass any config table; see below
+}
+```
+
+### packer.nvim
+
+```lua
+use {
+  "xiangnongWu2233/rubiks-cube.nvim",
+  cmd = "Rubikscube",
+  config = function() require("rubikscube").setup({}) end,
+}
+```
+
+## Usage
+
+```vim
+:Rubikscube
+```
+
+## Features
+
+- All 18 standard moves: face turns (`U D L R F B`) + cube rotations (`x y z`), each in CW/CCW form
+- Built-in timer with pause/resume on `<Space>`
+- Solve detection — flash + popup with time, move count, and personal best
+- Persistent best time stored at `stdpath("data")/rubikscube/best.json`
+- Floating window by default; configurable to open in current buffer, split, or vsplit
+- Fully configurable keymaps; any binding can be disabled with `false`
+
+Inside the cube buffer:
+
+| Key | Action |
+|---|---|
+| `u` / `U` | U face CW / CCW |
+| `d` / `D` | D face CW / CCW |
+| `l` / `L` | L face CW / CCW |
+| `r` / `R` | R face CW / CCW |
+| `f` / `F` | F face CW / CCW |
+| `b` / `B` | B face CW / CCW |
+| `x` / `X` | rotate whole cube around R axis |
+| `y` / `Y` | rotate whole cube around U axis |
+| `z` / `Z` | rotate whole cube around F axis |
+| `<Space>` | start / pause timer |
+| `s` | scramble (default 20 random moves) |
+| `<CR>` | reset to solved (clears timer) |
+| `?` | toggle help popup |
+| `q` | quit |
+
+Lowercase = clockwise face turn (Singmaster notation); uppercase = prime (counter-clockwise).
+
+## Configuration
+
+Default:
+
+```lua
+require("rubikscube").setup({
+  keymaps = {
+    -- Face turns: configure the lowercase letter; uppercase auto-binds the prime.
+    U = "u", D = "d", L = "l", R = "r", F = "f", B = "b",
+    -- Cube rotations: same convention.
+    x = "x", y = "y", z = "z",
+    -- Actions.
+    scramble = "s",
+    reset    = "<CR>",
+    timer    = "<Space>",
+    quit     = "q",
+    help     = "?",
+    -- Any entry above may be set to `false` to skip the binding entirely.
+  },
+  scramble_length = 20,   -- moves applied by the scramble action
+  persist_best    = true, -- set false to disable writing best.json (reads still work)
+  open_in         = "float", -- "float" | "current" | "split" | "vsplit"
+})
+```
+
+## Colors
+
+Sticker colors are exposed as the highlight groups:
+
+```
+RubiksW   white
+RubiksY   yellow
+RubiksO   orange
+RubiksR   red
+RubiksG   green
+RubiksB   blue
+```
+
+Override any of them from your colorscheme — they're set with `default = true`, so user overrides survive a plugin reload:
+
+```vim
+highlight RubiksO guibg=#ff8800 guifg=#000000
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `:Rubikscube` | Open the cube (no-op if a cube is already open) |

assets/rubiks-cub.png

@@ -0,0 +1,77 @@
+-- Persists the user's best solve time as JSON in stdpath("data").
+-- Schema: { time_ms = number, move_count = number, recorded_at = epoch_seconds }
+
+local M = {}
+
+-- Tests set this to redirect reads/writes away from the real data dir.
+M._path_override = nil
+
+local function path()
+  return M._path_override or (vim.fn.stdpath("data") .. "/rubikscube/best.json")
+end
+
+local function ensure_parent_dir()
+  -- pcall: degrade gracefully on read-only data dirs instead of aborting the solve flow.
+  if M._path_override then
+    local dir = vim.fn.fnamemodify(M._path_override, ":h")
+    if dir ~= "" then
+      pcall(vim.fn.mkdir, dir, "p")
+    end
+  else
+    pcall(vim.fn.mkdir, vim.fn.stdpath("data") .. "/rubikscube", "p")
+  end
+end
+
+function M.read()
+  local p = path()
+  local fh = io.open(p, "r")
+  if not fh then
+    return nil
+  end
+  local s = fh:read("*a")
+  fh:close()
+  if not s or s == "" then
+    return nil
+  end
+  local ok, data = pcall(vim.json.decode, s)
+  if not ok or type(data) ~= "table" then
+    return nil
+  end
+  return data
+end
+
+function M.write(data)
+  ensure_parent_dir()
+  local fh, err = io.open(path(), "w")
+  if not fh then
+    return false, err
+  end
+  fh:write(vim.json.encode(data))
+  fh:close()
+  return true
+end
+
+-- Returns the prior best time (ms) and whether `elapsed_ms` is a new best.
+-- Writes the new best if it improves on the prior. nil elapsed is a no-op.
+function M.maybe_update(elapsed_ms, move_count)
+  if type(elapsed_ms) ~= "number" then
+    return nil, false
+  end
+  local prior = M.read()
+  local prior_ms = prior and prior.time_ms
+  if prior_ms and prior_ms <= elapsed_ms then
+    return prior_ms, false
+  end
+  M.write({
+    time_ms = elapsed_ms,
+    move_count = move_count,
+    recorded_at = os.time(),
+  })
+  return prior_ms, true
+end
+
+function M.clear()
+  os.remove(path())
+end
+
+return M

lua/rubikscube/best.lua

@@ -0,0 +1,46 @@
+local M = {}
+
+-- Face base letters: lowercase = clockwise, uppercase (auto) = prime.
+-- Rotation base letters: same lowercase/uppercase convention.
+-- Action keys: lhs strings passed to vim.keymap.set.
+-- Any keymap entry may be set to `false` to skip that binding entirely.
+M.defaults = {
+  keymaps = {
+    U = "u",
+    D = "d",
+    L = "l",
+    R = "r",
+    F = "f",
+    B = "b",
+    x = "x",
+    y = "y",
+    z = "z",
+    scramble = "s",
+    reset = "<CR>",
+    timer = "<Space>",
+    quit = "q",
+    help = "?",
+  },
+  scramble_length = 20, -- moves applied by the scramble action
+  persist_best = true, -- false → solves never write best.json (reads still work)
+  open_in = "float", -- "float" | "current" | "split" | "vsplit"
+}
+
+M.current = vim.deepcopy(M.defaults)
+
+function M.apply(opts)
+  if type(opts) ~= "table" then
+    return
+  end
+  M.current = vim.tbl_deep_extend("force", M.current, opts)
+end
+
+function M.reset()
+  M.current = vim.deepcopy(M.defaults)
+end
+
+function M.get()
+  return M.current
+end
+
+return M