Merge pull request #4 from link-foundation/issue-3-e87aeca07ea0

feat: Add CLI tool with full glab auth login options and use command-stream

Author: konard

.changeset/cli-tool-and-command-stream.md

@@ -0,0 +1,12 @@
+---
+'glab-setup-git-identity': minor
+---
+
+Add CLI tool and update library to use command-stream
+
+- Add `glab-setup-git-identity` CLI command with all `glab auth login` options
+- Update README.md to match gh-setup-git-identity structure with "Instead of manually running" section
+- Refactor library to use command-stream for shell command execution
+- Add support for all glab auth login options: --hostname, --token, --stdin, --git-protocol, --api-protocol, --api-host, --use-keyring, --job-token
+- Add lino-arguments dependency for CLI argument parsing
+- Update TypeScript definitions with new options (apiProtocol, apiHost, jobToken, stdin)

README.md

@@ -1,47 +1,219 @@
 # glab-setup-git-identity
 
-Setup git identity using GitLab CLI (glab) - Configure `git user.name` and `user.email` from your GitLab account.
+A tool to setup git identity based on current GitLab user.
 
-Similar to [gh-setup-git-identity](https://github.com/link-foundation/gh-setup-git-identity) but for GitLab.
+[![npm version](https://img.shields.io/npm/v/glab-setup-git-identity)](https://www.npmjs.com/package/glab-setup-git-identity)
+[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## Overview
+
+`glab-setup-git-identity` is a CLI tool that simplifies setting up your git identity using your GitLab account. It automatically fetches your GitLab username and primary email address, then configures git with these values.
+
+Instead of manually running:
+
+```bash
+glab auth login --hostname gitlab.com --git-protocol https
+glab auth git-credential # For HTTPS authentication helper
+
+USERNAME=$(glab api user --jq '.username')
+EMAIL=$(glab api user --jq '.email')
+
+git config --global user.name "$USERNAME"
+git config --global user.email "$EMAIL"
+```
+
+You can simply run:
+
+```bash
+glab-setup-git-identity
+```
+
+## Features
+
+- **Automatic identity setup**: Fetches username and email from GitLab
+- **Global and local configuration**: Configure git globally or per-repository
+- **Authentication check**: Prompts you to login if not authenticated
+- **Git credential helper setup**: Automatically configures git to use GitLab CLI for HTTPS authentication
+- **Dry-run mode**: Preview changes without making them
+- **Cross-platform**: Works on macOS, Linux, and Windows
+- **Verbose mode**: Built-in verbose mode for debugging
+- **Self-hosted GitLab support**: Works with GitLab.com and self-hosted instances
 
 ## Prerequisites
 
-- [GitLab CLI (glab)](https://gitlab.com/gitlab-org/cli) installed
-- Authenticated with GitLab via `glab auth login`
+- Node.js >= 20.0.0 (or Bun >= 1.0.0)
+- Git (installed and configured)
+- GitLab CLI (`glab`) installed
+
+To install GitLab CLI, see: https://gitlab.com/gitlab-org/cli#installation
 
 ## Installation
 
+### Global Installation (CLI)
+
+```bash
+# Using npm
+npm install -g glab-setup-git-identity
+
+# Using bun
+bun install -g glab-setup-git-identity
+```
+
+### Local Installation (Library)
+
 ```bash
 # Using npm
 npm install glab-setup-git-identity
 
 # Using bun
 bun install glab-setup-git-identity
+```
+
+## CLI Usage
+
+### Basic Usage
+
+```bash
+# Setup git identity globally (default)
+glab-setup-git-identity
+
+# Setup git identity for current repository only
+glab-setup-git-identity --local
+
+# Preview what would be configured (dry run)
+glab-setup-git-identity --dry-run
+
+# Verify current git identity configuration
+glab-setup-git-identity --verify
+
+# Enable verbose output
+glab-setup-git-identity --verbose
+```
+
+### CLI Options
+
+```
+Usage: glab-setup-git-identity [options]
+
+Git Identity Options:
+  --global, -g         Set git config globally (default: true)
+  --local, -l          Set git config locally (in current repository)
+  --dry-run, --dry     Dry run - show what would be done without making changes
+  --verify             Verify current git identity configuration
+  --verbose, -v        Enable verbose output
+
+GitLab Authentication Options:
+  --hostname           GitLab hostname to authenticate with (default: gitlab.com)
+  --token, -t          GitLab access token (reads from stdin if --stdin is used)
+  --stdin              Read token from standard input
+  --git-protocol, -p   Protocol for git operations: ssh, https, or http (default: https)
+  --api-protocol       Protocol for API calls: https or http (default: https)
+  --api-host           Custom API host URL
+  --use-keyring        Store token in system keyring
+  --job-token, -j      CI job token for authentication
+
+General Options:
+  --help, -h           Show help
+  --version            Show version number
+```
+
+### Advanced Authentication Examples
+
+```bash
+# Authenticate with self-hosted GitLab
+glab-setup-git-identity --hostname gitlab.company.com
+
+# Use SSH protocol instead of HTTPS
+glab-setup-git-identity --git-protocol ssh
+
+# Authenticate with token from environment variable
+echo "$GITLAB_TOKEN" | glab-setup-git-identity --stdin
+
+# Use token-based authentication directly
+glab-setup-git-identity --token glpat-xxxxx
+
+# Store credentials in system keyring
+glab-setup-git-identity --use-keyring
+
+# Use in CI/CD with job token
+glab-setup-git-identity --job-token "$CI_JOB_TOKEN" --hostname gitlab.company.com
+```
+
+### First Run (Not Authenticated)
+
+If you haven't authenticated with GitLab CLI yet, the tool will automatically start the authentication process:
+
+```
+GitLab CLI is not authenticated. Starting authentication...
+
+Starting GitLab CLI authentication...
 
-# Using yarn
-yarn add glab-setup-git-identity
+? What GitLab instance do you want to log into? gitlab.com
+? What is your preferred protocol for Git operations? HTTPS
+? How would you like to login? Token
 
-# Using pnpm
-pnpm add glab-setup-git-identity
+Tip: you can generate a Personal Access Token here https://gitlab.com/-/profile/personal_access_tokens
+The minimum required scopes are 'api' and 'write_repository'.
+? Paste your authentication token:
 ```
 
-## Quick Start
+The tool runs `glab auth login` automatically, followed by configuring git to use GitLab CLI as the credential helper. Follow the prompts to complete login.
 
-### Manual Setup (using glab directly)
+If automatic authentication fails, you can run the commands manually:
 
 ```bash
-# Install glab CLI
-brew install glab  # macOS
-# or see https://gitlab.com/gitlab-org/cli#installation for other platforms
+glab auth login --hostname gitlab.com --git-protocol https
+```
+
+### Successful Run
+
+```
+Fetching GitLab user information...
+  GitLab user: your-username
+  GitLab email: your-email@example.com
+
+Configuring git (global)...
+  Git identity configured successfully!
+
+  Git configured:
+    user.name:  your-username
+    user.email: your-email@example.com
+  Scope: global (--global)
 
-# Authenticate with GitLab
-glab auth login
+Git identity setup complete!
 
-# Clone a repository
-git clone https://gitlab.com/your-username/your-repo
+You can verify your configuration with:
+  glab auth status
+  git config --global user.name
+  git config --global user.email
 ```
 
-### Using this library
+### Verifying Configuration
+
+You can verify your git identity configuration at any time using:
+
+```bash
+glab-setup-git-identity --verify
+```
+
+Or by running the verification commands directly:
+
+```bash
+glab auth status
+git config --global user.name
+git config --global user.email
+```
+
+For local repository configuration, use `--local`:
+
+```bash
+glab-setup-git-identity --verify --local
+git config --local user.name
+git config --local user.email
+```
+
+## Library Usage
 
 ```javascript
 import {
@@ -103,11 +275,17 @@ await runGlabAuthLogin({
   gitProtocol: 'https', // 'ssh', 'https', or 'http'
   useKeyring: true, // store token in OS keyring
 });
+
+// Login with CI job token
+await runGlabAuthLogin({
+  hostname: 'gitlab.company.com',
+  jobToken: 'CI_JOB_TOKEN_VALUE',
+});
 ```
 
 #### `runGlabAuthSetupGit(options?)`
 
-Configure git to use GitLab CLI as a credential helper for HTTPS operations. This is the equivalent of `gh auth setup-git` for GitHub CLI.
+Configure git to use GitLab CLI as a credential helper for HTTPS operations.
 
 Without this configuration, `git push/pull` may fail with "could not read Username" error when using HTTPS protocol.
 
@@ -219,6 +397,7 @@ console.log(defaultAuthOptions);
 // {
 //   hostname: 'gitlab.com',
 //   gitProtocol: 'https',
+//   apiProtocol: 'https',
 //   useKeyring: false
 // }
 ```
@@ -240,6 +419,12 @@ await setupGitIdentity({
 });
 ```
 
+Or via CLI:
+
+```bash
+glab-setup-git-identity --hostname gitlab.company.com
+```
+
 ## TypeScript Support
 
 This package includes TypeScript type definitions. All interfaces are exported: