@pc360/chlog 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog
+#Changelog
 
 All notable changes to this project are documented in this file.
 
@@ -8,8 +8,28 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ### Changed
 
+- No changes yet.
+
+## [0.1.11] - 2026-02-15
+
+### Added
+
+- Added explicit terminal environment requirements in README (macOS Terminal, iTerm2, Git Bash for Windows, WSL2, Linux)
+- Added detailed Git Bash login shell configuration guide
+- Added cross-platform npm global PATH setup instructions
+- Added structured shell setup section per environment
+- Improved documentation clarity for Windows users
+- Standardized installation and verification steps
+- Refined README structure for better onboarding experience
+
+## [0.1.10] - 2026-02-15
+
+### Changed
+
 - Removed Ink card border lines so help and status output no longer render inside a box.
 - Added blank lines before and after help and error output to improve readability.
+- Reorganized README onboarding flow into: installation, first-time dry-run usage, and troubleshooting.
+- Added explicit `command not found: chlog` guidance, including PATH updates for `~/.zshrc` / `~/.bashrc` (with `~/.zhsrc` note).
 
 ## [0.1.9] - 2026-02-14
 
@@ -21,7 +41,7 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ### Changed
 
-- Update docs
+- Update docs.
 
 ## [0.1.7] - 2026-02-14
 

package/README.md

@@ -2,261 +2,299 @@
 
 Internal CLI tool for creating structured changelog entries under:
 
-```
+```text
 changelog/unreleased/{added|changed|fixed|removed}
 ```
 
-The CLI now renders polished terminal cards using `ink` in interactive terminals, with plain-text fallback for scripts/CI.
-
-Each entry file is automatically:
+Each entry is automatically:
 
-- Named using Asia/Manila timestamp (`YYYYMMDDHHmmss`)
+- Named with Asia/Manila timestamp (`YYYYMMDDHHmmss`)
 - Placed in the correct type directory
-- Written as a single clean line
-- Prefixed with scope and layer (`Back-End` or `Front-End`)
+- Written as one clean line
+- Prefixed with scope and layer (`[Back-End]` or `[Front-End]`)
 
 ---
 
-## 📦 Install
+# 1. Installation
 
-```bash
-npm i -g @pc360/chlog
-```
+## Requirements
 
-## ✅ After Installation
+- Node.js `>= 18`
+- One of the following terminals:
+  - macOS Terminal
+  - iTerm2 (macOS)
+  - Git Bash (Windows)
+  - Linux bash/zsh
+  - WSL2 (Windows Subsystem for Linux)
 
-If `chlog` is not recognized after global install, add your npm global `bin` path to `PATH`.
-
-1. Get your npm prefix:
+Install globally:
 
 ```bash
-npm get prefix
+npm i -g @pc360/chlog
 ```
 
-2. Use the output as `<prefix>`, then add this to your shell config:
+Alternative (without global install):
 
 ```bash
-export PATH="$PATH:<prefix>/bin"
+npx @pc360/chlog --type <added|changed|fixed|removed> --scope <scope> --message "<description>"
 ```
 
-For `zsh`, add it to `~/.zshrc`.
-For `bash`, add it to `~/.bashrc`.
+---
 
-3. Reload your shell config (or open a new terminal):
+# 2. First-Time Usage (Dry Run Recommended)
+
+For first use, always run a dry run to preview output without creating a file:
 
 ```bash
-source ~/.zshrc
-# or
-source ~/.bashrc
+chlog --type added --scope JES-99 --message "Test entry" --dry-run
 ```
 
-Then run:
+Short form:
 
 ```bash
-# Dry run (preview only)
-chlog --type <added|changed|fixed|removed> \
-      --scope <scope> \
-      --message "<description>" \
-      [--frontend] \
-      --dry-run
-
-# Dry run short form (preview only)
-chlog -t <added|changed|fixed|removed> -s <scope> -m "<description>" [-f] -d
-
-# Create entry
-chlog --type <added|changed|fixed|removed> \
-      --scope <scope> \
-      --message "<description>" \
-      [--frontend]
+chlog -t added -s JES-99 -m "Test entry" -d
 ```
 
-You can also run it without global install:
+If the preview is correct, run the actual command:
 
 ```bash
-npx @pc360/chlog --type <added|changed|fixed|removed> \
-                 --scope <scope> \
-                 --message "<description>" \
-                 [--frontend]
+chlog --type added --scope JES-99 --message "Test entry"
 ```
 
 ---
 
-## 🚀 Usage
+# 3. If `chlog` Is Not Found
 
-```bash
-chlog --type <added|changed|fixed|removed> \
-      --scope <scope> \
-      --message "<description>" \
-      [--frontend]
+If you see `command not found: chlog` after installation, add npm global `bin` to your `PATH`.
 
-# Short form
-chlog -t <added|changed|fixed|removed> -s <scope> -m "<description>" [-f]
+Check npm prefix:
+
+```bash
+npm get prefix
 ```
 
+Then follow the setup instructions below depending on your environment.
+
 ---
 
-## 🧩 Parameters
+# 🖥 Shell Setup Per Environment
 
-| Flag             | Required | Description                                         |
-| ---------------- | -------- | --------------------------------------------------- |
-| `-t, --type`     | ✅       | Change type: `added`, `changed`, `fixed`, `removed` |
-| `-s, --scope`    | ✅       | Jira ticket or module name                          |
-| `-m, --message`  | ✅       | Description of the change                           |
-| `-f, --frontend` | ❌       | Uses `[Front-End]` instead of `[Back-End]`          |
-| `-d, --dry-run`  | ❌       | Preview file creation without writing               |
-| `-h, --help`     | ❌       | Show help                                           |
-| `-v, --version`  | ❌       | Show CLI version                                    |
+If `chlog` is installed globally but not found, ensure your npm global `bin` directory is included in your `PATH`.
 
 ---
 
-## 📝 Examples
+## 🍎 macOS Terminal / iTerm2
 
-### Back-End Change (Default)
+If using **zsh** (default on macOS):
 
-```
-chlog --type added --scope JES-33 --message "Add daily consolidated JE job"
+```bash
+echo 'export PATH="$PATH:$(npm get prefix)/bin"' >> ~/.zshrc
+source ~/.zshrc
 ```
 
-Creates:
+If using **bash**:
 
-```
-changelog/unreleased/added/20260213124530
+```bash
+echo 'export PATH="$PATH:$(npm get prefix)/bin"' >> ~/.bashrc
+source ~/.bashrc
 ```
 
-File content:
+Verify:
 
-```
-[JES-33] [Back-End] Add daily consolidated JE job
+```bash
+chlog --version
 ```
 
 ---
 
-### Front-End Change
+## 🪟 Git Bash (Windows)
+
+Git Bash runs as a **login shell**, which means it loads:
 
 ```
-chlog --type fixed --scope JES-45 --frontend --message "Fix table pagination issue"
+~/.bash_profile
 ```
 
-File content:
+If `.bash_profile` exists, it may NOT automatically load `.bashrc`.
+
+### Recommended Setup
+
+### Step 1: Ensure `.bash_profile` Loads `.bashrc`
 
+Open Git Bash:
+
+```bash
+nano ~/.bash_profile
 ```
-[JES-45] [Front-End] Fix table pagination issue
+
+Add:
+
+```bash
+# Load .bashrc if it exists
+if [ -f ~/.bashrc ]; then
+  . ~/.bashrc
+fi
 ```
 
+Save and exit.
+
 ---
 
-### Module-Based Scope
+### Step 2: Add npm Global Path to `.bashrc`
 
-```
-chlog --type changed --scope "Credit Validation" --message "Improve credit limit computation"
+```bash
+nano ~/.bashrc
 ```
 
-File content:
+Add:
 
-```
-[Credit Validation] [Back-End] Improve credit limit computation
+```bash
+export PATH="$PATH:$(npm get prefix)/bin"
 ```
 
+Save and restart Git Bash.
+
 ---
 
-## 📂 Directory Structure
+### Verify
 
+```bash
+chlog --version
 ```
-changelog/
-└── unreleased/
-    ├── added/
-    ├── changed/
-    ├── fixed/
-    └── removed/
-```
 
-Each entry is stored as a timestamp-named file:
+If the version prints, setup is successful.
+
+---
+
+## 🐧 WSL2 / Linux
+
+Add npm global path to:
 
+```bash
+~/.bashrc
 ```
-YYYYMMDDHHmmss
+
+Add:
+
+```bash
+export PATH="$PATH:$(npm get prefix)/bin"
 ```
 
-Timezone used: **Asia/Manila**
+Reload:
 
----
+```bash
+source ~/.bashrc
+```
 
-## 🔐 Rules Enforced by CLI
+Verify:
 
-- `--type` is required
-- `--scope` is required
-- `--message` is required
-- Prevents overwriting existing files
-- Automatically inserts `[Back-End]` or `[Front-End]`
-- Generates timestamp using Asia/Manila timezone
+```bash
+chlog --version
+```
 
 ---
 
-## 🧠 Recommended Conventions
+# Usage
 
-Preferred scope format:
+```bash
+chlog --type <added|changed|fixed|removed> \
+      --scope <scope> \
+      --message "<description>" \
+      [--frontend]
+```
 
-- Jira ticket: `JES-45`
-- Module name: `"Credit Validation"`
+Short form:
 
-Recommended message style:
+```bash
+chlog -t <added|changed|fixed|removed> -s <scope> -m "<description>" [-f]
+```
 
-- Use imperative mood
-- Start with capital letter
-- Do not end with period
+---
 
-Example:
+# Parameters
 
-```
-Add dealer credit validation logic
-Fix FR status blocking issue
-```
+| Flag             | Required | Description                                         |
+| ---------------- | -------- | --------------------------------------------------- |
+| `-t, --type`     | Yes      | Change type: `added`, `changed`, `fixed`, `removed` |
+| `-s, --scope`    | Yes      | Jira ticket or module name                          |
+| `-m, --message`  | Yes      | Description of the change                           |
+| `-f, --frontend` | No       | Uses `[Front-End]` instead of `[Back-End]`          |
+| `-d, --dry-run`  | No       | Preview file creation without writing               |
+| `-h, --help`     | No       | Show help                                           |
+| `-v, --version`  | No       | Show CLI version                                    |
 
 ---
 
-## 🧪 Dry Run Mode
+# Examples
 
-Preview without creating file:
+### Back-End (default)
 
+```bash
+chlog --type added --scope JES-33 --message "Add daily consolidated JE job"
 ```
-chlog --type added --scope JES-99 --message "Test entry" --dry-run
+
+### Front-End
+
+```bash
+chlog --type fixed --scope JES-45 --frontend --message "Fix table pagination issue"
 ```
 
----
+### Module Scope
 
-## 🛠 Node Version
+```bash
+chlog --type changed --scope "Credit Validation" --message "Improve credit limit computation"
+```
 
-Requires:
+---
 
+# Output Structure
+
+```text
+changelog/
+└── unreleased/
+    ├── added/
+    ├── changed/
+    ├── fixed/
+    └── removed/
 ```
-Node.js >= 18
+
+Entry filename format:
+
+```text
+YYYYMMDDHHmmss
 ```
 
-Runtime dependencies:
+Timezone used: `Asia/Manila`
 
-- `ink`
-- `react`
+---
+
+# CLI Rules
+
+- `--type` is required
+- `--scope` is required
+- `--message` is required
+- Existing files are not overwritten
+- Layer tag is auto-added (`[Back-End]` or `[Front-End]`)
 
 ---
 
-## 🧪 Running Unit Tests
+# 🧪 Running Unit Tests
 
 This project uses Node.js built-in test runner (`node:test`). No external test framework is required.
 
-### Run Tests
-
-From the project root:
+## Run Tests
 
-```
+```bash
 npm test
 ```
 
-Or directly with Node:
+Or directly:
 
-```
+```bash
 node --test
 ```
 
-### What Is Tested
+## What Is Tested
 
 - Argument parsing (`parseArgs`)
 - Required flag validation (`validateArgs`)
@@ -265,9 +303,3 @@ node --test
 - Output line formatting
 - Front-End vs Back-End label handling
 - Prevention of double label prefixing
-
----
-
-## 👨‍💻 Maintainer
-
-- almerleoalmazan@gmail.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pc360/chlog",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "PC360 Changelog CLI Tool",
   "author": "aalmazan@pcdsi.ph",
   "bin": {