From ca02cd96a4eba1b34b77aed50652b00c7d60925d Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:19:09 +0330
Subject: [PATCH 01/10] Prepare standalone npm CLI distribution

---
 package.json | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 9af507b..42c1024 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "code-life-balance",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "private": true,
   "license": "MIT",
   "repository": {
@@ -17,7 +17,9 @@
     "test:report": "node --test packages/report/index.test.mjs",
     "test": "node --test packages/core/index.test.mjs packages/report/index.test.mjs",
     "typecheck": "tsc --noEmit",
-    "check": "pnpm test && pnpm typecheck && pnpm build"
+    "check": "pnpm test && pnpm typecheck && pnpm build && pnpm test:npm-cli",
+    "build:npm-cli": "node scripts/build-npm-cli.mjs",
+    "test:npm-cli": "pnpm build:npm-cli && node dist/npm/cli/index.mjs --help && npm pack --dry-run ./dist/npm"
   },
   "dependencies": {
     "@base-ui/react": "^1.5.0",

From a842ff509f418eb14722db51394167fa1b33edd6 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:19:11 +0330
Subject: [PATCH 02/10] Add standalone npm CLI packager

---
 scripts/build-npm-cli.mjs | 67 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 scripts/build-npm-cli.mjs

diff --git a/scripts/build-npm-cli.mjs b/scripts/build-npm-cli.mjs
new file mode 100644
index 0000000..a88d70c
--- /dev/null
+++ b/scripts/build-npm-cli.mjs
@@ -0,0 +1,67 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { resolve } from "node:path"
+
+const root = process.cwd()
+const out = resolve(root, "dist/npm")
+const rootPackage = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"))
+
+await rm(out, { recursive: true, force: true })
+await mkdir(resolve(out, "cli"), { recursive: true })
+await mkdir(resolve(out, "packages/core"), { recursive: true })
+await mkdir(resolve(out, "packages/github-client"), { recursive: true })
+await mkdir(resolve(out, "packages/report"), { recursive: true })
+
+await cp(resolve(root, "cli/index.mjs"), resolve(out, "cli/index.mjs"))
+await cp(resolve(root, "packages/core/index.mjs"), resolve(out, "packages/core/index.mjs"))
+await cp(resolve(root, "packages/github-client/index.mjs"), resolve(out, "packages/github-client/index.mjs"))
+await cp(resolve(root, "packages/report/index.mjs"), resolve(out, "packages/report/index.mjs"))
+await cp(resolve(root, "LICENSE"), resolve(out, "LICENSE"))
+await cp(resolve(root, "docs/npm-cli-readme.md"), resolve(out, "README.md"))
+
+const packageJson = {
+  name: "code-life-balance",
+  version: rootPackage.version,
+  description: "Privacy-first GitHub activity and code-life balance reports from your local machine.",
+  type: "module",
+  bin: {
+    "code-life-balance": "./cli/index.mjs"
+  },
+  files: [
+    "cli",
+    "packages/core",
+    "packages/github-client",
+    "packages/report",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/alihd-tech/CodeLifeBalance.git"
+  },
+  homepage: "https://github.com/alihd-tech/CodeLifeBalance#readme",
+  bugs: {
+    url: "https://github.com/alihd-tech/CodeLifeBalance/issues"
+  },
+  keywords: [
+    "github",
+    "developer",
+    "activity",
+    "analytics",
+    "cli",
+    "privacy",
+    "productivity",
+    "code-life-balance"
+  ]
+}
+
+await writeFile(
+  resolve(out, "package.json"),
+  JSON.stringify(packageJson, null, 2) + "\n",
+  "utf8"
+)
+
+console.log(`Built npm CLI package at ${out}`)

From c2ff738ca398a04543773dfe42bbd1a73d512238 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:19:13 +0330
Subject: [PATCH 03/10] Add npm CLI package documentation

---
 docs/npm-cli-readme.md | 62 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/npm-cli-readme.md

diff --git a/docs/npm-cli-readme.md b/docs/npm-cli-readme.md
new file mode 100644
index 0000000..7f33e6f
--- /dev/null
+++ b/docs/npm-cli-readme.md
@@ -0,0 +1,62 @@
+# Code Life Balance CLI
+
+Run Code Life Balance locally without sending your GitHub credential or generated report to Code Life Balance infrastructure.
+
+## Run without installing
+
+```bash
+npx code-life-balance --username octocat --timezone Europe/Helsinki
+```
+
+Or install globally:
+
+```bash
+npm install --global code-life-balance
+code-life-balance --username octocat
+```
+
+## Authentication
+
+The CLI resolves credentials in this order:
+
+1. `GITHUB_TOKEN`, when present.
+2. Your existing `gh auth token` session.
+3. No token for public-only username analysis.
+
+For private owned-repository analysis:
+
+```bash
+gh auth login
+code-life-balance --include-private --timezone Europe/Helsinki
+```
+
+Private mode verifies that the authenticated token owner matches the username being analyzed.
+
+## Options
+
+```text
+--username <login>        GitHub username
+--timezone <IANA>         IANA timezone, default UTC
+--workday-start <0-23>    Workday start hour, default 9
+--workday-end <1-24>      Workday end hour, default 18
+--output-dir <path>       Output directory
+--theme <dark|light>      SVG theme
+--card-style <style>      detailed or compact
+--formats <list>          svg,json,markdown
+--include-private         Include authenticated private owned activity
+--public-only             Force public-only analysis
+--no-gh                   Do not read GitHub CLI authentication
+--help                    Show CLI help
+```
+
+Generated output can include:
+
+- `code-life.svg`
+- `stats.json`
+- `report.md`
+
+## Privacy
+
+The CLI calls the GitHub API directly from your machine. It does not send your GitHub token or generated report to a Code Life Balance service.
+
+Repository: https://github.com/alihd-tech/CodeLifeBalance

From fd1c00db65ce3b07a546b68e0f797183e61abeca Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:19:57 +0330
Subject: [PATCH 04/10] Set CLI distribution version to 1.2.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 42c1024..0834511 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "code-life-balance",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": true,
   "license": "MIT",
   "repository": {

From ae8956cfd5022290c98307f916272589fe697011 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:20:01 +0330
Subject: [PATCH 05/10] Allow release-driven npm CLI versions

---
 scripts/build-npm-cli.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/build-npm-cli.mjs b/scripts/build-npm-cli.mjs
index a88d70c..2287184 100644
--- a/scripts/build-npm-cli.mjs
+++ b/scripts/build-npm-cli.mjs
@@ -20,7 +20,7 @@ await cp(resolve(root, "docs/npm-cli-readme.md"), resolve(out, "README.md"))
 
 const packageJson = {
   name: "code-life-balance",
-  version: rootPackage.version,
+  version: process.env.CLI_PACKAGE_VERSION || rootPackage.version,
   description: "Privacy-first GitHub activity and code-life balance reports from your local machine.",
   type: "module",
   bin: {

From 23118b31b0efdfecfb031435445260c2c9752de3 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:20:04 +0330
Subject: [PATCH 06/10] Validate npm CLI package in CI

---
 .github/workflows/ci.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6a17c0b..7b2923a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,6 +44,9 @@ jobs:
       - name: Production build
         run: pnpm build
 
+      - name: Build and inspect npm CLI package
+        run: pnpm test:npm-cli
+
       - name: Self-test GitHub Action
         uses: ./
         with:

From d0f83b3246d78c9d2773cea99b1d72d7feaaac5e Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:20:06 +0330
Subject: [PATCH 07/10] Document npm CLI usage and packaging

---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 0c2e970..cc6613b 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,14 @@ For private owned repositories, create a user-owned fine-grained token with only
 
 ### Local CLI
 
+Once the npm package is published, run without installing:
+
+```bash
+npx code-life-balance --username octocat --timezone Europe/Helsinki
+```
+
+For repository development, or before the npm package is published, use `pnpm cli --`.
+
 Authenticate with GitHub CLI:
 
 ```bash
@@ -197,6 +205,8 @@ Open [http://localhost:3000](http://localhost:3000) and click **Analyze my GitHu
 | `pnpm typecheck` | Run strict TypeScript validation. |
 | `pnpm check` | Run tests, typecheck, and production build. |
 | `pnpm cli -- --help` | Show local CLI options. |
+| `pnpm build:npm-cli` | Build the dependency-free npm CLI package into `dist/npm`. |
+| `pnpm test:npm-cli` | Build, execute, and dry-run-pack the npm CLI artifact. |
 
 ## Deployment
 

From 16aba4316794dd77c2e7ff85c4f7db6c4e7d6208 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:20:18 +0330
Subject: [PATCH 08/10] Add OIDC npm CLI publishing workflow

---
 .github/workflows/publish-npm-cli.yml | 57 +++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 .github/workflows/publish-npm-cli.yml

diff --git a/.github/workflows/publish-npm-cli.yml b/.github/workflows/publish-npm-cli.yml
new file mode 100644
index 0000000..6a59f50
--- /dev/null
+++ b/.github/workflows/publish-npm-cli.yml
@@ -0,0 +1,57 @@
+name: Publish npm CLI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Semantic version to publish, for example 1.2.0"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate version
+        shell: bash
+        run: |
+          VERSION="${{ inputs.version }}"
+          [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+            echo "Version must be x.y.z"
+            exit 1
+          }
+
+      - name: Checkout matching release tag
+        uses: actions/checkout@v6
+        with:
+          ref: v${{ inputs.version }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build CLI package
+        env:
+          CLI_PACKAGE_VERSION: ${{ inputs.version }}
+        run: pnpm build:npm-cli
+
+      - name: Verify package
+        run: |
+          node dist/npm/cli/index.mjs --help
+          npm pack --dry-run ./dist/npm
+
+      - name: Publish with npm trusted publishing
+        run: npm publish ./dist/npm --access public

From 0709ff2f79c264390a4b6b8f31f7debb4ce58153 Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:20:20 +0330
Subject: [PATCH 09/10] Document secure npm publishing process

---
 docs/npm-publishing.md | 55 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/npm-publishing.md

diff --git a/docs/npm-publishing.md b/docs/npm-publishing.md
new file mode 100644
index 0000000..a80b40f
--- /dev/null
+++ b/docs/npm-publishing.md
@@ -0,0 +1,55 @@
+# Publishing the Code Life Balance CLI to npm
+
+The npm distribution is generated into `dist/npm`. It contains only the CLI and the shared runtime modules. It does not ship the Next.js website or web dependencies.
+
+## Build and verify locally
+
+```bash
+pnpm install
+pnpm test:npm-cli
+```
+
+The generated package has the unscoped npm name:
+
+```text
+code-life-balance
+```
+
+Users will be able to run:
+
+```bash
+npx code-life-balance --username octocat
+```
+
+## First publication
+
+npm trusted-publisher configuration requires the package to already exist. The first publication therefore needs to be performed once by an npm maintainer with 2FA:
+
+```bash
+pnpm build:npm-cli
+cd dist/npm
+npm login
+npm publish --access public
+```
+
+Before publishing, verify that the generated `package.json` has the intended version and that `npm pack --dry-run` lists only the CLI/shared runtime files.
+
+## Configure trusted publishing
+
+After the package exists on npmjs.com, open the package's trusted-publisher settings and add GitHub Actions:
+
+- GitHub owner: `alihd-tech`
+- Repository: `CodeLifeBalance`
+- Workflow filename: `publish-npm-cli.yml`
+- Allow action: direct `npm publish`
+
+The workflow uses a GitHub-hosted runner and `id-token: write`, so npm can authenticate it using OIDC without a long-lived npm publish token.
+
+## Subsequent releases
+
+1. Publish the matching GitHub release/tag, for example `v1.2.0`.
+2. Run **Publish npm CLI** from GitHub Actions.
+3. Enter `1.2.0`.
+4. The workflow checks out exactly `v1.2.0`, builds the CLI artifact, performs a dry-run pack, then publishes with npm trusted publishing.
+
+The workflow intentionally requires an exact release tag so npm packages cannot accidentally be built from a moving branch.

From 63f3ec4c5b019ab076db65583961e066c5a1866e Mon Sep 17 00:00:00 2001
From: Ali HD <85040609+alihd-tech@users.noreply.github.com>
Date: Mon, 21 Sep 2026 23:21:33 +0330
Subject: [PATCH 10/10] Fix CLI help template syntax

---
 cli/index.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cli/index.mjs b/cli/index.mjs
index 18f3a58..5cd0384 100644
--- a/cli/index.mjs
+++ b/cli/index.mjs
@@ -32,7 +32,7 @@ Options:
 
 Credentials:
   1. GITHUB_TOKEN environment variable, if set.
-  2. Otherwise `gh auth token`, unless --no-gh is passed.
+  2. Otherwise gh auth token, unless --no-gh is passed.
   3. Public analysis can run without a token when --username is provided.
 
 No credential or report is sent to CodeLifeBalance infrastructure.