@pc360/chlog 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -8,14 +8,28 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ### Changed
 
+- No changes yet.
+
+## [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
+
+### Changed
+
+- Update docs with a global installation and add --version option
 
 ## [0.1.8] - 2026-02-14
 
 ### Changed
 
-- Update docs
+- Update docs.
 
 ## [0.1.7] - 2026-02-14
 

package/README.md

@@ -2,101 +2,140 @@
 
 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
+- Written as one clean line
 - Prefixed with scope and layer (`Back-End` or `Front-End`)
 
----
+## 1. Installation
 
-## 🚀 Usage
+Requirements:
 
-```
-npx @pc360/chlog --type <added|changed|fixed|removed> \
-                         --scope <scope> \
-                         --message "<description>" \
-                         [--frontend]
+- Node.js `>= 18`
+
+Install globally:
 
-# Short form
-npx @pc360/chlog -t <added|changed|fixed|removed> -s <scope> -m "<description>" [-f]
+```bash
+npm i -g @pc360/chlog
 ```
 
----
+Alternative (without global install):
 
-## 🧩 Parameters
+```bash
+npx @pc360/chlog --type <added|changed|fixed|removed> --scope <scope> --message "<description>"
+```
 
-| 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                                           |
+## 2. First-Time Usage (Dry Run First)
 
----
+For first use, always run a dry run to preview output without creating a file:
 
-## 📝 Examples
+```bash
+chlog --type added --scope JES-99 --message "Test entry" --dry-run
+```
 
-### Back-End Change (Default)
+Short form:
 
-```
-npx @pc360/chlog --type added --scope JES-33 --message "Add daily consolidated JE job"
+```bash
+chlog -t added -s JES-99 -m "Test entry" -d
 ```
 
-Creates:
+If the preview is correct, run the actual command:
 
-```
-changelog/unreleased/added/20260213124530
+```bash
+chlog --type added --scope JES-99 --message "Test entry"
 ```
 
-File content:
+## 3. If `chlog` Is Not Found
 
+If you see `command not found: chlog` after installation, add npm global `bin` to your `PATH`.
+
+1. Get npm prefix:
+
+```bash
+npm get prefix
 ```
-[JES-33] [Back-End] Add daily consolidated JE job
+
+2. Add this line to your shell config (replace `<prefix>` with output above):
+
+```bash
+export PATH="$PATH:<prefix>/bin"
 ```
 
----
+3. Save to the right file:
+
+- `zsh`: `~/.zshrc` (or `~/.zhsrc` if your environment uses that filename)
+- `bash`: `~/.bashrc`
 
-### Front-End Change
+4. Reload shell:
 
+```bash
+source ~/.zshrc
+# or
+source ~/.bashrc
 ```
-npx @pc360/chlog --type fixed --scope JES-45 --frontend --message "Fix table pagination issue"
+
+5. Verify:
+
+```bash
+chlog --version
 ```
 
-File content:
+## Usage
 
+```bash
+chlog --type <added|changed|fixed|removed> \
+      --scope <scope> \
+      --message "<description>" \
+      [--frontend]
 ```
-[JES-45] [Front-End] Fix table pagination issue
+
+Short form:
+
+```bash
+chlog -t <added|changed|fixed|removed> -s <scope> -m "<description>" [-f]
 ```
 
----
+## Parameters
 
-### Module-Based Scope
+| 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                                    |
 
-```
-npx @pc360/chlog --type changed --scope "Credit Validation" --message "Improve credit limit computation"
-```
+## Examples
 
-File content:
+Back-End (default):
 
-```
-[Credit Validation] [Back-End] Improve credit limit computation
+```bash
+chlog --type added --scope JES-33 --message "Add daily consolidated JE job"
 ```
 
----
+Front-End:
 
-## 📂 Directory Structure
+```bash
+chlog --type fixed --scope JES-45 --frontend --message "Fix table pagination issue"
+```
+
+Module scope:
 
+```bash
+chlog --type changed --scope "Credit Validation" --message "Improve credit limit computation"
 ```
+
+## Output Structure
+
+```text
 changelog/
 └── unreleased/
     ├── added/
@@ -105,71 +144,21 @@ changelog/
     └── removed/
 ```
 
-Each entry is stored as a timestamp-named file:
+Entry filename format:
 
-```
+```text
 YYYYMMDDHHmmss
 ```
 
-Timezone used: **Asia/Manila**
-
----
+Timezone used: `Asia/Manila`
 
-## 🔐 Rules Enforced by CLI
+## CLI Rules
 
 - `--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
-
----
-
-## 🧠 Recommended Conventions
-
-Preferred scope format:
-
-- Jira ticket: `JES-45`
-- Module name: `"Credit Validation"`
-
-Recommended message style:
-
-- Use imperative mood
-- Start with capital letter
-- Do not end with period
-
-Example:
-
-```
-Add dealer credit validation logic
-Fix FR status blocking issue
-```
-
----
-
-## 🧪 Dry Run Mode
-
-Preview without creating file:
-
-```
-npx @pc360/chlog --type added --scope JES-99 --message "Test entry" --dry-run
-```
-
----
-
-## 🛠 Node Version
-
-Requires:
-
-```
-Node.js >= 18
-```
-
-Runtime dependencies:
-
-- `ink`
-- `react`
+- Existing files are not overwritten
+- Layer tag is auto-added (`[Back-End]` or `[Front-End]`)
 
 ---
 
@@ -200,9 +189,3 @@ node --test
 - Output line formatting
 - Front-End vs Back-End label handling
 - Prevention of double label prefixing
-
----
-
-## 👨‍💻 Maintainer
-
-- almerleoalmazan@gmail.com

package/bin/chlog.js

@@ -3,6 +3,7 @@
 
 const fs = require("fs/promises");
 const path = require("path");
+const { version } = require("../package.json");
 
 const {
   parseArgs,
@@ -39,6 +40,7 @@ Options:
   --tz "<iana>"          Timezone (default: Asia/Manila)
   -d, --dry-run          Preview only
   -h, --help             Show help
+  -v, --version          Show version
 `.trim();
 }
 
@@ -51,6 +53,11 @@ async function main() {
       process.exit(0);
     }
 
+    if (args.version) {
+      process.stdout.write(`${version}\n`);
+      process.exit(0);
+    }
+
     validateArgs(args);
 
     const timestamp = generateTimestamp(new Date(), args.tz);

package/lib/chlog-lib.js

@@ -11,6 +11,7 @@ function parseArgs(argv) {
     frontend: false,
     dryRun: false,
     help: false,
+    version: false,
   };
 
   for (let i = 2; i < argv.length; i++) {
@@ -21,6 +22,11 @@ function parseArgs(argv) {
       break;
     }
 
+    if (arg === "-v" || arg === "--version") {
+      args.version = true;
+      break;
+    }
+
     if (arg === "--dry-run" || arg === "-d") {
       args.dryRun = true;
       continue;

package/lib/chlog-ui.js

@@ -136,7 +136,7 @@ async function renderHelp(helpText) {
 
   const rendered = await renderInkCard(
     {
-      title: "PC360 Changelog CLI - v0.1.8",
+      title: "PC360 Changelog CLI",
       subtitle: "Usage & options",
       lines: styledLines,
       tone: "info",

package/package.json

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