glab-setup-git-identity 0.6.0

package/README.md

@@ -0,0 +1,455 @@
+# glab-setup-git-identity
+
+A tool to setup git identity based on current GitLab user.
+
+[![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
+
+- 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...
+
+? 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
+
+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:
+```
+
+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.
+
+If automatic authentication fails, you can run the commands manually:
+
+```bash
+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)
+
+Git identity setup complete!
+
+You can verify your configuration with:
+  glab auth status
+  git config --global user.name
+  git config --global user.email
+```
+
+### 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 {
+  isGlabAuthenticated,
+  runGlabAuthLogin,
+  runGlabAuthSetupGit,
+  setupGitIdentity,
+  verifyGitIdentity,
+} from 'glab-setup-git-identity';
+
+// Check if already authenticated
+const authenticated = await isGlabAuthenticated();
+
+if (!authenticated) {
+  // Run interactive login
+  await runGlabAuthLogin();
+}
+
+// Setup git credential helper for GitLab HTTPS operations
+// This configures git to use glab for authentication when pushing/pulling
+await runGlabAuthSetupGit();
+
+// Setup git identity from GitLab account
+const { username, email } = await setupGitIdentity();
+console.log(`Configured git as: ${username} <${email}>`);
+
+// Verify the configuration
+const identity = await verifyGitIdentity();
+console.log('Current git identity:', identity);
+```
+
+## API Reference
+
+### Authentication Functions
+
+#### `isGlabAuthenticated(options?)`
+
+Check if GitLab CLI is authenticated.
+
+```javascript
+const authenticated = await isGlabAuthenticated({
+  hostname: 'gitlab.company.com', // optional, for self-hosted GitLab
+  verbose: true, // optional, enable debug logging
+});
+```
+
+#### `runGlabAuthLogin(options?)`
+
+Run `glab auth login` interactively or with a token.
+
+```javascript
+// Interactive login
+await runGlabAuthLogin();
+
+// Login with token (non-interactive)
+await runGlabAuthLogin({
+  hostname: 'gitlab.com',
+  token: 'your-access-token',
+  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.
+
+Without this configuration, `git push/pull` may fail with "could not read Username" error when using HTTPS protocol.
+
+```javascript
+// Setup credential helper for gitlab.com
+await runGlabAuthSetupGit();
+
+// Setup for self-hosted GitLab
+await runGlabAuthSetupGit({
+  hostname: 'gitlab.company.com',
+  force: true, // overwrite existing configuration
+  verbose: true,
+});
+```
+
+The function automatically detects the glab installation path, so it works regardless of how glab was installed (Homebrew, apt, npm, etc.).
+
+#### `getGlabPath(options?)`
+
+Get the full path to the glab executable. Useful for debugging or custom integrations.
+
+```javascript
+const glabPath = await getGlabPath();
+console.log(`glab is installed at: ${glabPath}`);
+// e.g., /opt/homebrew/bin/glab, /usr/bin/glab, etc.
+```
+
+### User Information Functions
+
+#### `getGitLabUsername(options?)`
+
+Get the authenticated GitLab username.
+
+```javascript
+const username = await getGitLabUsername();
+```
+
+#### `getGitLabEmail(options?)`
+
+Get the primary email from the GitLab account.
+
+```javascript
+const email = await getGitLabEmail();
+```
+
+#### `getGitLabUserInfo(options?)`
+
+Get both username and email.
+
+```javascript
+const { username, email } = await getGitLabUserInfo({
+  hostname: 'gitlab.company.com', // optional
+});
+```
+
+### Git Configuration Functions
+
+#### `setGitConfig(key, value, options?)`
+
+Set a git configuration value.
+
+```javascript
+await setGitConfig('user.name', 'John Doe', {
+  scope: 'global', // or 'local'
+});
+```
+
+#### `getGitConfig(key, options?)`
+
+Get a git configuration value.
+
+```javascript
+const name = await getGitConfig('user.name', {
+  scope: 'global', // or 'local'
+});
+```
+
+### Identity Setup Functions
+
+#### `setupGitIdentity(options?)`
+
+Configure git identity based on GitLab user.
+
+```javascript
+const { username, email } = await setupGitIdentity({
+  hostname: 'gitlab.com', // optional
+  scope: 'global', // or 'local'
+  dryRun: false, // set to true to preview changes without applying
+  verbose: true, // enable debug logging
+});
+```
+
+#### `verifyGitIdentity(options?)`
+
+Get the current git identity configuration.
+
+```javascript
+const { username, email } = await verifyGitIdentity({
+  scope: 'global', // or 'local'
+});
+```
+
+### Default Options
+
+```javascript
+import { defaultAuthOptions } from 'glab-setup-git-identity';
+
+console.log(defaultAuthOptions);
+// {
+//   hostname: 'gitlab.com',
+//   gitProtocol: 'https',
+//   apiProtocol: 'https',
+//   useKeyring: false
+// }
+```
+
+## Token Requirements
+
+When using token-based authentication, ensure your GitLab access token has the following minimum scopes:
+
+- `api` - Full API access
+- `write_repository` - Push access to repositories
+
+## Self-Hosted GitLab
+
+All functions support the `hostname` option for self-hosted GitLab instances:
+
+```javascript
+await setupGitIdentity({
+  hostname: 'gitlab.company.com',
+});
+```
+
+Or via CLI:
+
+```bash
+glab-setup-git-identity --hostname gitlab.company.com
+```
+
+## TypeScript Support
+
+This package includes TypeScript type definitions. All interfaces are exported:
+
+```typescript
+import type {
+  AuthOptions,
+  AuthStatusOptions,
+  SetupGitOptions,
+  UserInfoOptions,
+  GitConfigOptions,
+  SetupOptions,
+  UserInfo,
+  GitIdentity,
+} from 'glab-setup-git-identity';
+```
+
+## Multi-Runtime Support
+
+This package works with:
+
+- **Node.js** (>=20.0.0)
+- **Bun** (>=1.0.0)
+- **Deno**
+
+## License
+
+[Unlicense](LICENSE) - Public Domain

package/bunfig.toml

@@ -0,0 +1,3 @@
+# Bun configuration
+# Note: Bun doesn't support excluding test files directly in config
+# Use CLI flags or file naming patterns instead

package/deno.json

@@ -0,0 +1,7 @@
+{
+  "nodeModulesDir": "auto",
+  "test": {
+    "include": ["tests/"],
+    "exclude": ["examples/", "node_modules/"]
+  }
+}

package/docs/case-studies/issue-13/README.md

@@ -0,0 +1,195 @@
+# Case Study: Robust Changeset CI/CD for Concurrent PRs
+
+## Issue Reference
+
+- **Issue**: [#13 - Apply latest CI/CD experience from hive-mind project](https://github.com/link-foundation/js-ai-driven-development-pipeline-template/issues/13)
+- **Reference PR**: [hive-mind#961 - Improve changeset CI/CD robustness for concurrent PRs](https://github.com/link-assistant/hive-mind/pull/961)
+- **Reference Issue**: [hive-mind#960 - Better changeset CI/CD](https://github.com/link-assistant/hive-mind/issues/960)
+
+## Timeline of Events
+
+### 2025-12-21 18:23 UTC - CI Failure Trigger
+
+A CI failure occurred on hive-mind PR #728 during the changeset validation step:
+
+```
+Found 4 changeset file(s)
+Error: Multiple changesets found (4). Each PR should have exactly ONE changeset.
+Error: Found changeset files:
+  fix-perlbrew-unbound-variable.md
+  increase-min-disk-space.md
+  readme-initialization.md
+  sync-package-lock-json.md
+Error: Process completed with exit code 1.
+```
+
+**Source**: [GitHub Actions Run #20413963959](https://github.com/link-assistant/hive-mind/actions/runs/20413963959/job/58654854890?pr=728)
+
+### 2025-12-22 06:31 UTC - Issue Created
+
+Issue #960 was created describing the problem and proposing a more robust changeset CI/CD system.
+
+### 2025-12-22 ~18:00 UTC - Solution Implemented
+
+PR #961 was created and merged implementing the solution.
+
+### 2025-12-22 19:22 UTC - Issue Closed
+
+Issue #960 was closed as the fix was merged.
+
+## Root Cause Analysis
+
+### The Problem
+
+The original `validate-changeset.mjs` script checked **all** changeset files in the `.changeset` directory:
+
+```javascript
+// Original problematic approach
+const changesetFiles = readdirSync(changesetDir).filter(
+  (file) => file.endsWith('.md') && file !== 'README.md'
+);
+
+if (changesetCount > 1) {
+  console.error(`Multiple changesets found (${changesetCount})`);
+  process.exit(1);
+}
+```
+
+This approach fails when:
+
+1. **Multiple PRs merge before a release cycle completes**: If PR-A merges with changeset-A, then PR-B opens, it will see changeset-A in the directory and fail validation even though PR-B only added changeset-B.
+
+2. **Race condition in concurrent development**: In active repositories, multiple contributors work simultaneously. If their PRs don't merge fast enough between release cycles, changesets accumulate.
+
+3. **Release process delay or failure**: If the release workflow fails (npm outage, CI failure), changesets accumulate and block all subsequent PRs.
+
+### Why This Happens
+
+The [changesets](https://github.com/changesets/changesets) workflow is designed to accumulate changes:
+
+> "When two changesets are included which are of the type minor, the minor release will only be bumped once."
+
+However, this design assumes:
+
+- The release workflow runs successfully after each merge
+- Or the PR validation is aware of what the PR actually added vs. what was pre-existing
+
+The original implementation violated the second assumption by treating all existing changesets as if they were added by the current PR.
+
+## Proposed Solutions
+
+### Solution 1: Check Only PR-Added Changesets (Implemented)
+
+Use `git diff` to compare the PR branch against the base branch and only validate changesets that were **added** by the current PR:
+
+```javascript
+// Get changeset files ADDED by this PR only
+const diffOutput = execSync(`git diff --name-status ${baseSha} ${headSha}`);
+const addedChangesets = [];
+
+for (const line of diffOutput.trim().split('\n')) {
+  const [status, filePath] = line.split('\t');
+  if (
+    status === 'A' &&
+    filePath.startsWith('.changeset/') &&
+    filePath.endsWith('.md')
+  ) {
+    addedChangesets.push(filePath);
+  }
+}
+```
+
+**Benefits**:
+
+- PRs are validated in isolation
+- Pre-existing changesets don't cause false failures
+- No need to merge default branch before PR can pass
+
+### Solution 2: Merge Multiple Changesets at Release Time
+
+During the release workflow, if multiple changesets exist, merge them into a single changeset before running `changeset version`:
+
+```javascript
+// Determine highest bump type (major > minor > patch)
+const highestBumpType = getHighestBumpType(parsedChangesets.map((c) => c.type));
+
+// Combine descriptions chronologically
+const descriptions = parsedChangesets
+  .sort((a, b) => a.mtime - b.mtime)
+  .map((c) => c.description);
+
+// Create merged changeset
+const mergedContent = createMergedChangeset(highestBumpType, descriptions);
+```
+
+**Benefits**:
+
+- Preserves changelog history from all changes
+- Uses correct version bump (highest severity wins)
+- Maintains chronological order of changes
+- Cleans up after merging
+
+### Solution 3: Environment Variables for Git Context
+
+Pass explicit SHA references from GitHub Actions to the validation script:
+
+```yaml
+- name: Check for changesets
+  env:
+    GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+    GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+  run: node scripts/validate-changeset.mjs
+```
+
+**Benefits**:
+
+- Reliable git context in CI
+- No need to fetch/calculate base branch
+- Works with shallow clones
+
+## Industry Best Practices
+
+According to [Changesets documentation](https://github.com/changesets/changesets):
+
+1. **Use the changeset bot** to detect missing changesets rather than failing builds
+2. **Not every commit needs a changeset** - docs and tests don't require releases
+3. **Changesets decouple intent from publishing** - team transparency
+
+According to [pnpm documentation](https://pnpm.io/using-changesets):
+
+1. **Changesets accumulate** and are processed together at release time
+2. **Multiple PRs with changesets** should merge cleanly
+3. **The release PR** handles version bumping and changelog generation
+
+According to [Infinum Frontend Handbook](https://infinum.com/handbook/frontend/changesets):
+
+1. **PRs created with GITHUB_TOKEN don't trigger other workflows**
+2. **Use a Personal Access Token (PAT)** for automated PRs that need CI checks
+3. **Changesets action** can automate versioning PRs
+
+## Files Changed in Reference PR #961
+
+| File                                     | Change Type | Purpose                                   |
+| ---------------------------------------- | ----------- | ----------------------------------------- |
+| `scripts/validate-changeset.mjs`         | Modified    | Check only PR-added changesets            |
+| `scripts/merge-changesets.mjs`           | Added       | Merge multiple changesets at release time |
+| `.github/workflows/release.yml`          | Modified    | Pass SHA env vars, add merge step         |
+| `experiments/test-changeset-scripts.mjs` | Added       | Comprehensive test suite                  |
+
+## Implementation Status
+
+This case study documents the analysis. The actual implementation will:
+
+1. Update `scripts/validate-changeset.mjs` to use git diff approach
+2. Add `scripts/merge-changesets.mjs` for release-time merging
+3. Update `.github/workflows/release.yml` with new steps
+4. Add tests in `experiments/test-changeset-scripts.mjs`
+5. Update README.md with design decision documentation
+
+## References
+
+- [Changesets GitHub Repository](https://github.com/changesets/changesets)
+- [Using Changesets with pnpm](https://pnpm.io/using-changesets)
+- [Infinum Frontend Handbook - Changesets](https://infinum.com/handbook/frontend/changesets)
+- [Automate NPM releases with changesets](https://dev.to/ignace/automate-npm-releases-on-github-using-changesets-25b8)
+- [Failed CI Run Log](https://github.com/link-assistant/hive-mind/actions/runs/20413963959/job/58654854890?pr=728)

package/docs/case-studies/issue-13/hive-mind-issue-960.json

@@ -0,0 +1,23 @@
+{
+  "author": {
+    "id": "MDQ6VXNlcjE0MzE5MDQ=",
+    "is_bot": false,
+    "login": "konard",
+    "name": "Konstantin Diachenko"
+  },
+  "body": "```\nRun # Skip changeset check for automated version PRs\nFound 4 changeset file(s)\nError: Multiple changesets found (4). Each PR should have exactly ONE changeset.\nError: Found changeset files:\n  fix-perlbrew-unbound-variable.md\n  increase-min-disk-space.md\n  readme-initialization.md\n  sync-package-lock-json.md\nError: Process completed with exit code 1.\n```\n\nSource: https://github.com/link-assistant/hive-mind/actions/runs/20413963959/job/58654854890?pr=728\n\nPlease make our changesets CI/CD much more robust.\n\nFirst of all in pull requests, we need to check only changesets added by the pull request, and that should be exactly one.\n\nIf there some changesets not yet processed, we need to make sure we do merge them in order they were created into single changeset.\n\nAlso for example if any of these changeset were minor the resulting merged changeset whould be minor, and so on.\n\nSo all previously unprocessed changesets will get a chance to be proccessed, but to reduce load on CI/CD we can just merge them in a sequence they they were arriving.\n\nAnd to a single version bump of previous one was unsuccesful.\n\nSo in all cases newly added changeset is checked only in the scope of the pull request, so it will never depend on what is in default branch, meaning there will be never need to pull changes from default branch and no possible conflicts abour it.\n\nEven on errors, unprocessed changesets will be just merged and published as soon we get error preventing release resolved.\n\nThe sequence of changesets is preserved. If you see any other potential issues, try to make sure they are handled properly to minimize the need for `git merge` or to minimize probability of conflicts.",
+  "closedAt": "2025-12-22T19:22:17Z",
+  "comments": [],
+  "createdAt": "2025-12-22T06:31:35Z",
+  "labels": [
+    {
+      "id": "LA_kwDOPUU0qc8AAAACGYm6iw",
+      "name": "bug",
+      "description": "Something isn't working",
+      "color": "d73a4a"
+    }
+  ],
+  "number": 960,
+  "state": "CLOSED",
+  "title": "Better changeset CI/CD"
+}