recent-project-checker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuki Shindo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,256 @@
+# recent-project-checker
+
+![Logo](https://github.com/shinshin86/recent-project-checker/raw/main/images/logo.png)
+
+シェル履歴から最近作業していたプロジェクトを推定し、再開しやすい順にランキング表示する CLI ツールです。
+
+[English README (README.md)](README.md)
+
+## Install
+
+インストール不要で試す:
+
+```bash
+npx recent-project-checker --root ~/projects
+```
+
+グローバルインストール:
+
+```bash
+npm install -g recent-project-checker
+```
+
+`recent-project-checker` と短縮エイリアス `recent-projects` の 2 つのコマンドが登録されます。
+
+## Quick Start
+
+```bash
+# 最近のプロジェクトをランキング表示（テキスト出力）
+recent-project-checker --root ~/projects
+
+# アクセス回数順で並べる
+recent-project-checker --root ~/projects --sort count
+
+# ローカル Web UI をブラウザで開く
+recent-project-checker --root ~/projects --web --open
+```
+
+## Features
+
+- `--root` 配下の `<root>/<project>/...` 構造からプロジェクトルートを推定
+- シェルコマンドから候補パスを抽出: `cd`, `pushd`, `git -C`, `git clone`, `make -C`, `docker compose -f`, `npm/pnpm/yarn --prefix|--cwd`, エディタ起動コマンド
+- `mkdir <dir> -> cd <dir> -> git init` のような新規作成フローも候補化
+- 頻度 + 最近性を組み合わせたスコアでランキング
+- `score` / `count` / `recent` / `timeline` でソート可能
+- テキストまたは構造化 JSON で出力（`--format text|json`）
+- ローカル Web UI 内蔵（`--web` / `--ui`）、フィルタリングとライブ再集計対応
+- 出現回数（`--min-count`）や期間（`--days`）でフィルタ
+
+## Usage
+
+### Options
+
+| オプション | 説明 | デフォルト |
+|---|---|---|
+| `--root <path>` | **必須。** プロジェクトを含むルートディレクトリ。 | — |
+| `--days <n>` | 集計対象の履歴日数。 | `60` |
+| `--limit <n>` | 表示する最大件数。 | `100` |
+| `--max-results <n>` | `--limit` の別名。 | `100` |
+| `--min-count <n>` | 候補に含める最低出現回数。 | `1` |
+| `--history <mode>` | 履歴ソース: `auto`, `zsh`, `bash`, `file`。 | `auto` |
+| `--file <path>` | 履歴ファイルのパス（`--history file` 時に必須）。 | — |
+| `--format <mode>` | 出力形式: `text` または `json`。 | `text` |
+| `--sort <mode>` | ソート: `score`, `count`, `recent`, `timeline`。 | `score` |
+| `--web`, `--ui` | 解析後にローカル Web UI を起動。 | — |
+| `--host <host>` | Web サーバーのホスト。 | `127.0.0.1` |
+| `--port <n>` | Web サーバーのポート。 | `4173` |
+| `--allow-remote` | ループバック以外のホストを許可（`--token` 必須）。 | — |
+| `--token <value>` | リモート公開時の Web UI/API アクセストークン。 | — |
+| `--open` | ブラウザを自動起動。 | — |
+| `--no-open` | ブラウザを自動起動しない。 | （デフォルト） |
+| `--help`, `-h` | ヘルプを表示。 | — |
+
+### Examples
+
+```bash
+# 直近 90 日に絞り、上位 40 件を表示
+recent-project-checker --root ~/projects --days 90 --limit 40
+
+# 特定の履歴ファイルを読み込み、JSON で出力
+recent-project-checker --root ~/projects --history file --file /path/to/.zsh_history --format json
+
+# 2 回以上アクセスしたプロジェクトのみ表示
+recent-project-checker --root /work/projects --min-count 2
+
+# 最終アクセス順で Web UI を起動
+recent-project-checker --root ~/projects --sort recent --web
+
+# LAN に公開（トークン必須）
+recent-project-checker --root ~/projects --web --host 0.0.0.0 --allow-remote --token 'your-token'
+
+# 起動後、Web UI の token 欄にトークンを入力
+```
+
+## Web UI (`--web` / `--ui`)
+
+```bash
+recent-project-checker --root ~/projects --web
+```
+
+- `http://127.0.0.1:4173` でローカル HTTP サーバーを起動します（デフォルトではブラウザを**自動起動しません**。`--open` で自動起動できます）。
+- フィルター入力欄でプロジェクト名を素早く絞り込めます。
+- UI 上で `days`、`limit`、`min-count`、`sort` を変更し、その場で再集計できます。
+- 各行の **copy** を押すと `cd "<repo-path>"` をクリップボードにコピーします。
+- ポートが衝突する場合は `--port` で変更してください。
+- 基本的には localhost での利用を想定しています。
+- ループバック以外で待受ける場合は `--allow-remote --token <value>` を併用し、Web UI の token 欄に入力してください。
+- リモート公開時は平文 HTTP なので、信頼できるネットワーク内でのみ利用するか、HTTPS/TLS 終端の背後で運用してください。
+- API クライアントからは `x-rpc-token` または `Authorization: Bearer <token>` ヘッダでトークンを送信してください。
+
+## How it works
+
+### Root structure
+
+`recent-project-checker` は以下の構造でリポジトリを推定します:
+
+```
+<root>/<project>/...
+```
+
+例:
+
+- `/workspace/cli-tool/src` -> プロジェクトルートは `/workspace/cli-tool`
+- `mkdir my-new-app && cd my-new-app && git init` の場合も、`--root` 配下であれば候補として登録されます。
+
+### Processing pipeline
+
+1. 履歴ファイルを読み込み（`--history auto` の場合、`~/.zsh_history` と `~/.bash_history` を順に探索）。
+2. 各コマンドを解析し、関連パスを抽出。
+3. `--root` 配下のパスのみ残し、プロジェクト単位に正規化。
+4. `mkdir -> cd -> git init` フローからも候補を追加。
+5. プロジェクトごとに `count` と最終アクセス時刻を集計。
+6. スコアを算出してソート。
+
+### パス判定ルール
+
+- 候補パスは、パスを伴うコマンドのみから抽出します: `cd`, `pushd`, `git -C`, `git clone`, `make -C`, `docker compose -f`, `npm/pnpm/yarn --prefix|--cwd`, エディタ起動コマンド（`code`, `vim`, `nvim`, `open`, `cursor`, `subl`）。
+- `--sort recent` は並び順のみを変更します。表示されるには、まず抽出・フィルタ条件を通過している必要があります。
+- `--root` の外側のパスは除外します。
+- 通常のコマンド由来パスは `<root>/<root配下の先頭セグメント>` に正規化します。
+- `mkdir <dir> -> cd <dir> -> git init` の場合は、`git init` されたディレクトリ自体（`--root` 配下のネスト含む）を候補として保持します。
+
+### 疑似 cwd 追跡
+
+各履歴ファイルごとに、コマンドを先頭から順に読みながら疑似 `cwd` を更新します。
+
+- 初期 `cwd` は `--root` です。
+- `cd` はシェルに近いルールで疑似 `cwd` を更新します:
+  - `cd` または `cd --` -> `$HOME`
+  - `cd -` -> 直前の `cwd`
+  - `cd <relative|absolute>` -> 解決後のパス
+- `pushd <path>` でも疑似 `cwd` を更新します。
+- 安全策として、遷移先が「実在ディレクトリ」または同一履歴内で先に `mkdir` 済みのときだけ更新します。
+
+### Scoring
+
+```
+score = log2(1 + count) + recency
+recency = max(0, 1.2 - 経過日数 / 30)
+```
+
+`zsh` では履歴内タイムスタンプを使用します。
+`bash` の通常形式にタイムスタンプがない場合は、行の位置から簡易推定を行い `--days` フィルタに対応します。
+
+## JSON output (`--format json`)
+
+```json
+{
+  "generatedAt": "2026-02-13T00:00:00.000Z",
+  "options": {
+    "root": "...",
+    "historyFiles": ["..."],
+    "days": 60,
+    "minCount": 1,
+    "limit": 100,
+    "sort": "score",
+    "format": "json",
+    "version": "0.1.0"
+  },
+  "results": [
+    {
+      "repo": "/path/to/root/owner/repo",
+      "count": 3,
+      "last": {
+        "unix": 1700000000,
+        "iso": "2024-11-14T22:13:20.000Z"
+      },
+      "score": 4.2
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+- **履歴に `cd` が少ない / 検出されない**
+  `--days` を広げるか、`--history file --file <path>` で別の履歴ファイルを指定してみてください。
+- **`bash` 履歴にタイムスタンプがない**
+  zsh の履歴ソースが使える場合はそちらを使用するか、`--days` を大きくしてください。`HISTTIMEFORMAT` で拡張履歴を有効化すると推定精度が上がります。
+- **`--root` の配下が `<root>/<project>` 形式でない**
+  `--root` の指定や階層構造を見直してください。
+- **テキストと JSON で表示が違う**
+  ランキングロジックは同一です。表示形式の違いのみです。
+
+## Requirements
+
+- Node.js >= 18
+- macOS / Linux（Windows は主要ターゲットではありませんが、パス処理は安全に劣化するよう設計されています）
+
+## Development
+
+ソースから直接実行（インストール不要）:
+
+```bash
+node src/cli.js --root ~/projects
+```
+
+リポジトリからローカルインストール:
+
+```bash
+npm install -g .
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+テストスイートの構成:
+
+- 単体テスト（20 件以上）: `parseZshLine`, `extractDirsFromCmd`, `toRepoRoot`, スコアリング, 引数パース
+- E2E テスト（2 件以上）: テキスト出力, JSON 出力
+
+### Lint & Format
+
+```bash
+npm run lint
+npm run format
+```
+
+<details>
+<summary>Design decisions and alternatives</summary>
+
+- **`--root` は常に必須** — 環境固有パスをハードコードせず、誤検出を防止しています。
+  - 代替案: `~/workspace` などをデフォルト値にすることも可能ですが、誤検出のリスクが高いと判断しました。
+- **`--max-results` は `--limit` の別名** — 互換性を維持しつつオプションの重複を回避しています。
+  - 代替案: 片方を廃止する方法もありますが、既存の呼び出しを壊す可能性があります。
+- **`bash` タイムスタンプの位置ベースフォールバック** — `bash` 履歴にタイムスタンプがない場合、行の位置から概算で推定します。
+  - 代替案: シェルレベルのトレース解析でより高精度にできますが、現段階ではコスト対効果に見合いません。
+- **本ツールは完全復元ではなく「再開支援」のためのヒント生成ツールです。** 依存は意図的に最小限にしています。
+
+</details>
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,256 @@
+# recent-project-checker
+
+![Logo](https://github.com/shinshin86/recent-project-checker/raw/main/images/logo.png)
+
+Estimate recently used projects from shell history and show a ranked list to quickly resume work.
+
+[日本語版 README はこちら (README.ja.md)](README.ja.md)
+
+## Install
+
+Try without installing:
+
+```bash
+npx recent-project-checker --root ~/projects
+```
+
+Or install globally:
+
+```bash
+npm install -g recent-project-checker
+```
+
+The package registers two commands: `recent-project-checker` and the shorter alias `recent-projects`.
+
+## Quick Start
+
+```bash
+# Ranked list of recent projects (text output)
+recent-project-checker --root ~/projects
+
+# Sort by how many times each project was accessed
+recent-project-checker --root ~/projects --sort count
+
+# Open the local Web UI in your browser
+recent-project-checker --root ~/projects --web --open
+```
+
+## Features
+
+- Infers project roots under `--root` using the `<root>/<project>/...` structure
+- Extracts candidate paths from shell commands: `cd`, `pushd`, `git -C`, `git clone`, `make -C`, `docker compose -f`, `npm/pnpm/yarn --prefix|--cwd`, and editor launchers
+- Detects newly created projects from `mkdir <dir> -> cd <dir> -> git init` flows
+- Ranks candidates by a combined frequency + recency score
+- Supports sorting by `score`, `count`, `recent`, and `timeline`
+- Outputs text or structured JSON (`--format text|json`)
+- Built-in local Web UI (`--web` / `--ui`) with filtering and live re-aggregation
+- Filters by minimum occurrences (`--min-count`) and date range (`--days`)
+
+## Usage
+
+### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--root <path>` | **Required.** Root directory containing project directories. | — |
+| `--days <n>` | Number of days of history to consider. | `60` |
+| `--limit <n>` | Maximum number of results to show. | `100` |
+| `--max-results <n>` | Alias for `--limit`. | `100` |
+| `--min-count <n>` | Minimum times a candidate must appear. | `1` |
+| `--history <mode>` | History source: `auto`, `zsh`, `bash`, or `file`. | `auto` |
+| `--file <path>` | Path to history file (required when `--history file`). | — |
+| `--format <mode>` | Output format: `text` or `json`. | `text` |
+| `--sort <mode>` | Sort mode: `score`, `count`, `recent`, or `timeline`. | `score` |
+| `--web`, `--ui` | Start local Web UI after analysis. | — |
+| `--host <host>` | Host for the web server. | `127.0.0.1` |
+| `--port <n>` | Port for the web server. | `4173` |
+| `--allow-remote` | Allow non-loopback host (requires `--token`). | — |
+| `--token <value>` | Access token for Web UI/API when remote. | — |
+| `--open` | Open browser automatically. | — |
+| `--no-open` | Do not open browser automatically. | (default) |
+| `--help`, `-h` | Show help. | — |
+
+### Examples
+
+```bash
+# Narrow to last 90 days, show top 40
+recent-project-checker --root ~/projects --days 90 --limit 40
+
+# Read a specific history file and output JSON
+recent-project-checker --root ~/projects --history file --file /path/to/.zsh_history --format json
+
+# Only show projects accessed 2+ times
+recent-project-checker --root /work/projects --min-count 2
+
+# Web UI sorted by most recent access
+recent-project-checker --root ~/projects --sort recent --web
+
+# Expose Web UI to LAN (token required)
+recent-project-checker --root ~/projects --web --host 0.0.0.0 --allow-remote --token 'your-token'
+
+# Then enter the token in the Web UI token field
+```
+
+## Web UI (`--web` / `--ui`)
+
+```bash
+recent-project-checker --root ~/projects --web
+```
+
+- Starts a local HTTP server at `http://127.0.0.1:4173` (browser is **not** opened by default; use `--open` to auto-launch).
+- Filter input to quickly narrow project names.
+- Adjust `days`, `limit`, `min-count`, and `sort` in the UI, then re-aggregate on the fly.
+- Click **copy** to copy `cd "<repo-path>"` to the clipboard.
+- If the port is busy, specify another with `--port`.
+- This feature is primarily intended for localhost use.
+- For non-loopback hosts, use `--allow-remote --token <value>`, then enter the token in the UI token field.
+- Remote mode serves plain HTTP; use only trusted networks or place it behind HTTPS/TLS.
+- For API clients, send token via `x-rpc-token` or `Authorization: Bearer <token>` header.
+
+## How it works
+
+### Root structure
+
+`recent-project-checker` assumes repositories live under:
+
+```
+<root>/<project>/...
+```
+
+For example:
+
+- `/workspace/cli-tool/src` -> project root is `/workspace/cli-tool`
+- `mkdir my-new-app && cd my-new-app && git init` also registers the new directory as a candidate under `--root`.
+
+### Processing pipeline
+
+1. Load history files (`~/.zsh_history` and `~/.bash_history` when `--history auto`).
+2. Parse each command and extract relevant paths.
+3. Keep only paths under `--root` and normalize to the project level.
+4. Add candidates from `mkdir -> cd -> git init` flows.
+5. Aggregate `count` and latest access time per project.
+6. Calculate score and sort.
+
+### Path decision rules
+
+- Candidate paths are extracted from path-bearing commands only: `cd`, `pushd`, `git -C`, `git clone`, `make -C`, `docker compose -f`, `npm/pnpm/yarn --prefix|--cwd`, and editor launchers (`code`, `vim`, `nvim`, `open`, `cursor`, `subl`).
+- `--sort recent` only changes ordering. A directory must first pass extraction and filtering to appear in results.
+- Paths outside `--root` are excluded.
+- Normal command-derived paths are normalized to `<root>/<first-segment-under-root>`.
+- For `mkdir <dir> -> cd <dir> -> git init`, the initialized directory itself is preserved as a candidate (including nested paths under `--root`).
+
+### Simulated cwd tracking
+
+For each history file, this tool tracks a simulated `cwd` while scanning commands in order.
+
+- Initial `cwd` is `--root`.
+- `cd` updates simulated `cwd` with shell-like semantics:
+  - `cd` or `cd --` -> `$HOME`
+  - `cd -` -> previous `cwd`
+  - `cd <relative|absolute>` -> resolved path
+- `pushd <path>` also updates simulated `cwd`.
+- Safety guard: the simulated `cwd` is updated only when destination is an existing directory, or a directory created earlier in the same history stream (`mkdir` tracking).
+
+### Scoring
+
+```
+score = log2(1 + count) + recency
+recency = max(0, 1.2 - elapsedDays / 30)
+```
+
+`zsh` history timestamps are used when present.
+For `bash` entries without timestamps, a positional fallback estimation is used so that `--days` filtering still works.
+
+## JSON output (`--format json`)
+
+```json
+{
+  "generatedAt": "2026-02-13T00:00:00.000Z",
+  "options": {
+    "root": "...",
+    "historyFiles": ["..."],
+    "days": 60,
+    "minCount": 1,
+    "limit": 100,
+    "sort": "score",
+    "format": "json",
+    "version": "0.1.0"
+  },
+  "results": [
+    {
+      "repo": "/path/to/root/owner/repo",
+      "count": 3,
+      "last": {
+        "unix": 1700000000,
+        "iso": "2024-11-14T22:13:20.000Z"
+      },
+      "score": 4.2
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+- **Few or no `cd` commands are detected**
+  Increase `--days` or specify another history file with `--history file --file <path>`.
+- **No timestamps in `bash` history**
+  Use the zsh history source if available, or increase `--days`.
+- **`--root` path structure does not follow `<root>/<project>`**
+  Adjust `--root` or your repository layout.
+- **Output differs between text and JSON**
+  Ranking logic is the same; only the presentation format differs.
+
+## Requirements
+
+- Node.js >= 18
+- macOS / Linux (Windows is not a primary target, but path handling degrades safely)
+
+## Development
+
+Run from source (without installing):
+
+```bash
+node src/cli.js --root ~/projects
+```
+
+Install locally from the repo:
+
+```bash
+npm install -g .
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+Test suite includes:
+
+- Unit tests (20+ cases): `parseZshLine`, `extractDirsFromCmd`, `toRepoRoot`, scoring, arg parsing
+- End-to-end tests (2+ cases): text output, JSON output
+
+### Lint & Format
+
+```bash
+npm run lint
+npm run format
+```
+
+<details>
+<summary>Design decisions and alternatives</summary>
+
+- **`--root` is always required** — no default root is assumed to avoid environment-specific assumptions and accidental misdetection.
+  - Alternative: hardcode a default like `~/workspace`, but the risk of false positives is too high.
+- **`--max-results` as an alias for `--limit`** — keeps compatibility while avoiding option duplication.
+  - Alternative: drop one of them, but that could break existing invocations.
+- **Positional fallback for `bash` timestamps** — when `bash` history has no timestamps, line position is used as a rough estimate.
+  - Alternative: shell-level trace parsing for better precision, but the complexity cost is not justified at this stage.
+- **This is a restart-assistance tool, not a full restoration mechanism.** Dependencies are intentionally minimal.
+
+</details>
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "recent-project-checker",
+  "version": "0.1.0",
+  "description": "Estimate recently used projects from shell history and show restart-ready candidates.",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "recent-project-checker": "./src/cli.js",
+    "recent-projects": "./src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "biome check src tests",
+    "format": "biome format src tests"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "history",
+    "project",
+    "resume",
+    "node"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^1.8.3"
+  }
+}