Skip to content

Commit d5f3d07

Browse files
KikolatorKikolator
committed
feat: --help, proj-config, tests & CI tweaks (v0.1.3)
1 parent 9adf301 commit d5f3d07

File tree

10 files changed

+198
-14
lines changed

10 files changed

+198
-14
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,28 @@
11
name: lint
2-
on: [push]
2+
on:
3+
push:
4+
branches: [ main ]
5+
pull_request:
6+
37
jobs:
48
test:
59
runs-on: ubuntu-latest
610
steps:
7-
- uses: actions/checkout@v4
8-
- name: ShellCheck
9-
uses: ludeeus/action-shellcheck@v2
10-
- name: Bats
11-
uses: mig4/setup-bats@v1
12-
- run: bats test
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
with:
14+
fetch-depth: 0 # allow git-describe etc. to work later
15+
16+
- name: Install ShellCheck
17+
run: |
18+
sudo apt-get update -qq
19+
sudo apt-get install -y shellcheck
20+
21+
- name: Run ShellCheck
22+
run: shellcheck $(git ls-files '*.sh' '*.zsh')
23+
24+
- name: Set up Bats
25+
uses: mig4/setup-bats@v3
26+
27+
- name: Run Bats tests
28+
run: bats test

‎CHANGELOG.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Changelog
2+
3+
All notable changes to **proj‑jumper** are documented in this file.<br>
4+
This project follows the [Keep a Changelog](https://keepachangelog.com/) convention and uses [Semantic Versioning](https://semver.org/).
5+
6+
## [Unreleased]
7+
8+
## [0.1.3] - 2025‑06‑30
9+
10+
### Added
11+
12+
- `proj --help` / `proj -h` now prints a detailed usage guide.
13+
14+
### Changed
15+
16+
- Refactored main function to route `--help` before directory checks.
17+
18+
## [0.1.2] - 2025‑06‑30
19+
20+
### Added
21+
22+
- `proj-config` helper command for one‑line root setup.
23+
- Updated README with Homebrew‑only install instructions and config helper docs.
24+
25+
### Changed
26+
27+
- Homebrew caveats now remind users to set `PROJ_DEV_ROOT` or run `proj-config`.
28+
29+
## [0.1.1] - 2025‑06‑30
30+
31+
### Fixed
32+
33+
- Renamed `proj.plugin.zsh` → `proj-jumper.plugin.zsh` so Oh My Zsh can load the plugin without warnings.
34+
35+
## [0.1.0] - 2025‑06‑30
36+
37+
### Added
38+
39+
- Initial public release:
40+
41+
- `proj` command with interactive picker and tab completion.
42+
- Smart root‑mount detection.
43+
- Homebrew tap formula and MIT license.

‎proj-jumper.plugin.zsh‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,42 @@
11
#!/usr/bin/env zsh
2-
# proj-jumper — jump to a project inside $DEV_ROOT
3-
4-
# --- configuration ----------------------------------------------------------
5-
: ${DEV_ROOT:=${PROJ_DEV_ROOT:-"/Volumes/dog_house/development/projects"}}
2+
# proj-jumper — jump quickly into a project directory under $DEV_ROOT
3+
# v0.1.3-dev
64

5+
# -------- configuration ------
6+
: ${DEV_ROOT:=${PROJ_DEV_ROOT:-"~/development"}}
77
# allow users to export PROJ_DEV_ROOT or DEV_ROOT to override
88
export DEV_ROOT
99

10-
# --- function ---------------------------------------------------------------
10+
# ───────── help text ─────────
11+
_proj_usage() {
12+
cat <<EOF
13+
proj-jumper — jump to project directories
14+
15+
Usage:
16+
proj <name> cd into the project called <name>
17+
proj interactive picker (fzf if available, else list)
18+
proj -h | --help show this help
19+
20+
Options:
21+
-h, --help display this help and exit
22+
23+
Environment variables:
24+
PROJ_DEV_ROOT override the default root path ($DEV_ROOT)
25+
DEV_ROOT same as above (kept for compatibility)
26+
27+
Examples:
28+
proj savage → cd \$DEV_ROOT/savage
29+
proj → fuzzy-select a project
30+
proj-config ~/code → write export PROJ_DEV_ROOT=~/code to ~/.zshrc
31+
EOF
32+
}
33+
34+
35+
# ───────── main command ─────────
1136
proj () {
37+
# 0. help first
38+
[[ "$1" == "-h" || "$1" == "--help" ]] && { _proj_usage; return 0 }
39+
1240
# 1. verify disk
1341
[[ -d $DEV_ROOT ]] || { print -u2 "⚠️ $DEV_ROOT not found"; return 1 }
1442

@@ -31,7 +59,7 @@ proj () {
3159
fi
3260
}
3361

34-
# ---------------------------------- config helper
62+
# ───────── config helper ─────────
3563
proj-config () {
3664
local new_root=${1:-}
3765
[[ -z $new_root ]] && {
@@ -52,7 +80,7 @@ proj-config () {
5280
}
5381
compdef _files proj-config # tab-complete directories
5482

55-
# --- completion hook --------------------------------------------------------
83+
# ─────── completion helpers ───────
5684
# Late-bound because the volume could mount after shell start
5785
_proj_complete () {
5886
[[ -d $DEV_ROOT ]] || return

‎test/completion.bats‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/usr/bin/env bats
2+
3+
@test "_proj_complete suggests directories in DEV_ROOT" {
4+
fake_root="$(mktemp -d)"
5+
mkdir "$fake_root/alpha" "$fake_root/beta"
6+
7+
run zsh -c '
8+
export DEV_ROOT="'"$fake_root"'"
9+
source "$BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh"
10+
reply=() # zsh completions are returned in $reply
11+
_proj_complete "" # call the completion function
12+
print -l "${reply[@]}"
13+
'
14+
15+
[ "$status" -eq 0 ]
16+
[[ "$output" == *"alpha"* ]]
17+
[[ "$output" == *"beta"* ]]
18+
}

‎test/proj_config_sets_root.bats‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#!/usr/bin/env bats
2+
3+
@test "proj-config appends PROJ_DEV_ROOT export to .zshrc" {
4+
temp_home="$(mktemp -d)"
5+
export ZDOTDIR="$temp_home" # make plugin look here for .zshrc
6+
touch "$ZDOTDIR/.zshrc"
7+
8+
new_root="$(mktemp -d)"
9+
10+
run zsh -c '
11+
source "$BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh"
12+
proj-config "'"$new_root"'"
13+
'
14+
15+
# command succeeds
16+
[ "$status" -eq 0 ]
17+
18+
# line actually added
19+
grep -q "export PROJ_DEV_ROOT=$new_root" "$ZDOTDIR/.zshrc"
20+
}

‎test/proj_help.bats‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env bats
2+
3+
setup() {
4+
load '../test_helpers/load_plugin' # tiny helper that sources the plugin
5+
}
6+
7+
@test "proj --help prints usage" {
8+
run proj --help
9+
[ "$status" -eq 0 ]
10+
[[ "$output" == *"Usage:"* ]]
11+
}

‎test/proj_jump_success.bats‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
@test "proj jumps into existing directory" {
2+
fake_root=$(mktemp -d)
3+
mkdir "$fake_root/alpha"
4+
export DEV_ROOT="$fake_root"
5+
run bash -c "source $BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh; proj alpha; pwd"
6+
[ "$status" -eq 0 ]
7+
[[ "$output" == "$fake_root/alpha" ]]
8+
}

‎test/proj_root_missing.bats‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/usr/bin/env bats
2+
3+
load 'test_helper/bats-support/load' # optional if bats-support is available
4+
load 'test_helper/bats-assert/load' # optional if bats-assert is available
5+
6+
@test "proj warns and exits 1 when DEV_ROOT is missing" {
7+
missing_root="$(mktemp -d)"
8+
rmdir "$missing_root" # ensure the directory truly does not exist
9+
10+
run zsh -c "
11+
export DEV_ROOT='$missing_root'
12+
source \"\$BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh\"
13+
proj
14+
"
15+
16+
[ "$status" -eq 1 ]
17+
[[ "$output" == ⚠️* ]] || [[ "$output" == *'not found'* ]]
18+
}

‎test/proj_unknown_project.bats‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/usr/bin/env bats
2+
3+
load 'test_helper/bats-support/load' # optional
4+
load 'test_helper/bats-assert/load' # optional
5+
6+
@test "proj exits 1 and warns when project does not exist" {
7+
fake_root="$(mktemp -d)"
8+
mkdir "$fake_root/alpha" # a real directory to prove root exists
9+
10+
run zsh -c "
11+
export DEV_ROOT='$fake_root'
12+
source \"$BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh\"
13+
proj doesnotexist
14+
"
15+
16+
[ "$status" -eq 1 ]
17+
[[ "$output" == *'No such project'* ]]
18+
}

‎test/test_helpers/load_plugin‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/usr/bin/env bash
2+
# Args: none — sources plugin with an isolated HOME
3+
export HOME=$(mktemp -d)
4+
source "$BATS_TEST_DIRNAME/../proj-jumper.plugin.zsh"

0 commit comments

Comments
 (0)