tmux-fuzzy-motion 0.0.1 → 0.0.3

package/README.ja.md

@@ -0,0 +1,141 @@
+# tmux-fuzzy-motion
+
+[English README](./README.md)
+
+`tmux-fuzzy-motion` は、`tmux copy-mode` 内で素早くカーソル移動するための
+CLI です。現在の viewport からジャンプ対象を抽出し、fuzzy search で絞り込み、
+大文字の hint で移動できます。英字のローマ字 query に対しては Migemo による
+日本語マッチも行います。
+
+## 特徴
+
+- `tmux copy-mode` 内で動作
+- 現在の viewport から URL、path、filename、symbol、一般的な単語を抽出
+- `fzf` による fuzzy match
+- `jsmigemo` による英字 query の Migemo マッチ
+- overlay 描画時も pane の色を維持
+- 単一キーの大文字 hint で素早く選択
+- query は対象 pane 内に描画し、終了時に元の pane を復元
+
+## 動作要件
+
+- Node.js 22 以上
+- tmux 3.2 以上
+
+## インストール
+
+```bash
+npm install -g tmux-fuzzy-motion@latest
+```
+
+pnpm を使う場合:
+
+```bash
+pnpm add -g tmux-fuzzy-motion@latest
+```
+
+インストール確認:
+
+```bash
+tmux-fuzzy-motion doctor
+```
+
+グローバル install せずにその場で実行する場合:
+
+```bash
+npx tmux-fuzzy-motion@latest doctor
+```
+
+## tmux 設定
+
+`tmux.conf` に次を追加してください。
+
+```tmux
+bind-key -T copy-mode-vi s run-shell -b 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'
+bind-key -T copy-mode s run-shell -b 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'
+```
+
+設定変更後は tmux を reload します。
+
+```bash
+tmux source-file ~/.tmux.conf
+```
+
+## 使い方
+
+1. `copy-mode` に入る
+2. `s` を押す
+3. 小文字や記号で query を入力する
+4. fuzzy match で候補を絞り込む
+5. 英字 query の場合は Migemo による日本語候補も対象になる
+6. 大文字 hint を押して即座に移動する
+7. `Esc` または `Ctrl-[` でキャンセルする
+
+## 入力キー
+
+- `A-Z`: 表示中の hint を即時選択
+- `Enter`: 現在の先頭候補を選択
+- `Esc`, `Ctrl-[`, `Ctrl-g`: キャンセル
+- `Backspace`, `Ctrl-h`: 1 文字削除
+- `Ctrl-w`: 直前の単語を削除
+- `Ctrl-u`: query をすべて削除
+
+## コマンド
+
+```text
+tmux-fuzzy-motion start <pane-id> <client-tty>
+tmux-fuzzy-motion doctor
+```
+
+`input` は `start` から内部的に使うサブコマンドです。
+
+## Doctor
+
+ローカル環境の確認には `doctor` を使います。
+
+```bash
+tmux-fuzzy-motion doctor
+```
+
+確認内容:
+
+- Node.js の version
+- tmux の version
+- Migemo 辞書の読み込み可否
+
+## 開発
+
+このリポジトリからローカル開発する場合:
+
+```bash
+pnpm install
+```
+
+この開発フローでは `pnpm` が必要です。
+
+1 回 build:
+
+```bash
+pnpm build
+```
+
+watch build:
+
+```bash
+pnpm run dev
+```
+
+ローカルの一括確認:
+
+```bash
+pnpm check
+```
+
+## 制約
+
+- 対象は現在の viewport のみ
+- `copy-mode` 専用
+- query 入力は ASCII 寄り
+- combining character の完全な扱いは未保証
+- overlay は一時的な tmux pane を swap して表示し、終了時に元へ戻す
+- query は pane 内の最下行右端に描画する

package/README.md

@@ -1,45 +1,141 @@
 # tmux-fuzzy-motion
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[日本語版はこちら](./README.ja.md)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+`tmux-fuzzy-motion` is a CLI for quick cursor jumps inside `tmux copy-mode`.
+It scans the current viewport, extracts jump targets, filters them with fuzzy
+search, and lets you jump with uppercase hints. Roman queries can also match
+Japanese text through Migemo.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Features
 
-## Purpose
+- Works inside `tmux copy-mode`
+- Extracts URLs, paths, filenames, symbols, and general words from the current viewport
+- Supports fuzzy matching with `fzf`
+- Supports Migemo matching for alphabetic queries via `jsmigemo`
+- Preserves pane colors while drawing the overlay
+- Uses single-key uppercase hints for fast selection
+- Renders the query inside the target pane and restores the original pane after finishing
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `tmux-fuzzy-motion`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Requirements
 
-## What is OIDC Trusted Publishing?
+- Node.js 22 or later
+- tmux 3.2 or later
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Install
 
-## Setup Instructions
+```bash
+npm install -g tmux-fuzzy-motion@latest
+```
 
-To properly configure OIDC trusted publishing for this package:
+If you prefer pnpm:
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```bash
+pnpm add -g tmux-fuzzy-motion@latest
+```
 
-## DO NOT USE THIS PACKAGE
+Verify the installation:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```bash
+tmux-fuzzy-motion doctor
+```
 
-## More Information
+You can also run it without a global install:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```bash
+npx tmux-fuzzy-motion@latest doctor
+```
 
----
+## tmux Configuration
 
-**Maintained for OIDC setup purposes only**
+Add these bindings to your `tmux.conf`:
+
+```tmux
+bind-key -T copy-mode-vi s run-shell -b 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'
+bind-key -T copy-mode s run-shell -b 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'
+```
+
+Reload tmux after editing the config:
+
+```bash
+tmux source-file ~/.tmux.conf
+```
+
+## Usage
+
+1. Enter `copy-mode`.
+2. Press `s`.
+3. Type a query in lowercase or symbols.
+4. Narrow the candidates with fuzzy matching.
+5. For alphabetic queries, Migemo also expands roman input to Japanese matches.
+6. Press an uppercase hint to jump immediately.
+7. Press `Esc` or `Ctrl-[` to cancel.
+
+## Input Keys
+
+- `A-Z`: select a visible hint immediately
+- `Enter`: select the first visible match
+- `Esc`, `Ctrl-[`, `Ctrl-g`: cancel
+- `Backspace`, `Ctrl-h`: delete one character
+- `Ctrl-w`: delete the previous word
+- `Ctrl-u`: clear the whole query
+
+## Commands
+
+```text
+tmux-fuzzy-motion start <pane-id> <client-tty>
+tmux-fuzzy-motion doctor
+```
+
+`input` is an internal subcommand used by `start`.
+
+## Doctor
+
+Use `doctor` to verify the local environment:
+
+```bash
+tmux-fuzzy-motion doctor
+```
+
+It checks:
+
+- Node.js version
+- tmux version
+- Migemo dictionary loading
+
+## Development
+
+For local development from this repository:
+
+```bash
+pnpm install
+```
+
+You will need `pnpm` for the development workflow above.
+
+Build once:
+
+```bash
+pnpm build
+```
+
+Watch mode:
+
+```bash
+pnpm run dev
+```
+
+Run the full local check:
+
+```bash
+pnpm check
+```
+
+## Limitations
+
+- Targets are limited to the current viewport
+- Designed for `copy-mode` only
+- Query input is ASCII-oriented
+- Exact behavior for combining characters is not fully guaranteed
+- The overlay swaps in a temporary tmux pane and restores the original pane when it exits
+- The query is drawn on the bottom row inside the pane, aligned to the right edge