gitxplain 0.1.9 → 0.2.1

package/.github/workflows/ci.yml

@@ -16,6 +16,8 @@ jobs:
         with:
           node-version: '20'
           cache: npm
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
       - name: Install dependencies
         run: npm ci
       - name: Lint

package/.github/workflows/release.yml

@@ -2,12 +2,13 @@ name: Release
 on:
   push:
     tags:
-      - '*.*.*'
+      - 'v*'
+permissions:
+  contents: write
 jobs:
-  publish:
+  release:
+    if: startsWith(github.ref_name, 'v')
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -16,12 +17,98 @@ jobs:
         with:
           node-version: '20'
           cache: npm
-          registry-url: 'https://registry.npmjs.org/'
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
       - name: Install dependencies
         run: npm ci
+      - name: Derive release metadata
+        id: meta
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "deb_path=dist/gitxplain_${VERSION}_all.deb" >> "${GITHUB_OUTPUT}"
       - name: Test
         run: npm test
+      - name: Build Debian package
+        run: ./scripts/build-deb.sh
+      - name: Verify npm token
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "NPM_TOKEN is not configured for this repository."
+            echo "Add it in GitHub: Settings -> Secrets and variables -> Actions -> New repository secret."
+            exit 1
+          fi
+          printf "//registry.npmjs.org/:_authToken=%s\n" "${NODE_AUTH_TOKEN}" > "${HOME}/.npmrc"
+          npm whoami
       - name: Publish to npm
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm publish
+      - name: Compute npm tarball SHA-256
+        id: npm
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TARBALL_URL="https://registry.npmjs.org/gitxplain/-/gitxplain-${VERSION}.tgz"
+          curl -fsSL "${TARBALL_URL}" -o "gitxplain-${VERSION}.tgz"
+          SHA256="$(sha256sum "gitxplain-${VERSION}.tgz" | awk '{print $1}')"
+          echo "tarball_url=${TARBALL_URL}" >> "${GITHUB_OUTPUT}"
+          echo "sha256=${SHA256}" >> "${GITHUB_OUTPUT}"
+      - name: Checkout Homebrew tap
+        uses: actions/checkout@v4
+        with:
+          repository: guruswarupa/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: homebrew-tap
+      - name: Update Homebrew formula
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          SHA256="${{ steps.npm.outputs.sha256 }}"
+          FORMULA_PATH="homebrew-tap/Formula/gitxplain.rb"
+          mkdir -p "$(dirname "${FORMULA_PATH}")"
+          cat > "${FORMULA_PATH}" <<EOF
+          class Gitxplain < Formula
+            desc "AI-powered Git commit explainer CLI"
+            homepage "https://github.com/guruswarupa/gitxplain"
+            url "https://registry.npmjs.org/gitxplain/-/gitxplain-${VERSION}.tgz"
+            sha256 "${SHA256}"
+            license "MIT"
+
+            depends_on "node"
+
+            def install
+              libexec.install Dir["package/*"]
+              bin.install_symlink libexec/"cli/index.js" => "gitxplain"
+              bin.install_symlink libexec/"cli/index.js" => "gitxplore"
+            end
+
+            test do
+              assert_match "gitxplain", shell_output("#{bin}/gitxplain --help")
+            end
+          end
+          EOF
+      - name: Commit and push Homebrew tap changes
+        working-directory: homebrew-tap
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/gitxplain.rb
+          if git diff --cached --quiet; then
+            echo "No Homebrew formula changes to commit."
+            exit 0
+          fi
+          git commit -m "gitxplain ${GITHUB_REF_NAME}"
+          git push
+      - name: Create GitHub release and upload Debian package
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ steps.meta.outputs.deb_path }}
+      - name: Print AUR update instructions
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          SHA256="${{ steps.npm.outputs.sha256 }}"
+          echo "Manual AUR update steps:"
+          echo "1. Update packaging/aur/PKGBUILD with pkgver=${VERSION} and sha256sums=('${SHA256}')."
+          echo "2. Run: makepkg --printsrcinfo > .SRCINFO"
+          echo "3. Commit PKGBUILD and .SRCINFO to the AUR git repository and push."

package/README.md

@@ -46,6 +46,43 @@ Supported providers:
 - A Git repository in your current working directory
 - An API key for your chosen provider, or a local Ollama instance
 
+## Installation
+
+Install from npm:
+
+```bash
+npm install -g gitxplain
+```
+
+Install from bun:
+
+```bash
+bun install -g gitxplain
+```
+
+Install with Homebrew:
+
+```bash
+brew tap guruswarupa/homebrew-tap
+brew install gitxplain
+```
+
+Install from the AUR:
+
+```bash
+yay -S gitxplain
+```
+
+```bash
+paru -S gitxplain
+```
+
+Install from a Debian package downloaded from GitHub Releases:
+
+```bash
+sudo apt install ./gitxplain_<version>_all.deb
+```
+
 Optional advanced environment variables:
 
 - `LLM_PROVIDER` default: `openai`

package/cli/index.js

@@ -689,8 +689,16 @@ async function runPipelineCommand(cwd) {
     return 0;
   }
 
-  const { writtenFiles, notes } = writePipelineFiles(cwd, analysis, selection);
-  console.log(`\nCreated workflow files: ${writtenFiles.join(", ")}`);
+  const { writtenFiles, updatedFiles, unchangedFiles, notes } = writePipelineFiles(cwd, analysis, selection);
+
+  if (updatedFiles.length === 0 && unchangedFiles.length > 0) {
+    console.log(`\nWorkflow files already matched the current template: ${unchangedFiles.join(", ")}`);
+  } else if (updatedFiles.length > 0 && unchangedFiles.length === 0) {
+    console.log(`\nUpdated workflow files: ${updatedFiles.join(", ")}`);
+  } else {
+    console.log(`\nUpdated workflow files: ${updatedFiles.join(", ")}`);
+    console.log(`Unchanged workflow files: ${unchangedFiles.join(", ")}`);
+  }
 
   if (notes.length > 0) {
     console.log(`\n${notes.join("\n")}`);
@@ -765,6 +773,10 @@ export async function main(argv = process.argv) {
     return 0;
   }
 
+  if (parsed.pipelineCommand) {
+    return runPipelineCommand(cwd);
+  }
+
   if (
     parsed.addCommand ||
     parsed.removeCommand ||

package/cli/services/mergeService.js

@@ -33,6 +33,10 @@ function unique(values) {
   return [...new Set(values)];
 }
 
+function formatVersionTag(version) {
+  return `v${version}`;
+}
+
 function extractVersions(line) {
   return unique(line.match(VERSION_PATTERN) ?? []);
 }
@@ -319,23 +323,26 @@ export function selectReleaseWindows(sourceCommits, releaseCommits = []) {
 export function selectReleaseTags(sourceCommits, existingTagNames = [], existingTagTargets = []) {
   const windows = selectLatestWindowsPerVersion(buildReleaseWindows(sourceCommits));
   const taggedVersions = extractTaggedVersions(existingTagNames);
-  const targetByVersion = new Map(
+  const existingTagByVersion = new Map(
     existingTagTargets
       .map((tag) => {
         const version = tag.tagName?.match(TAG_VERSION_PATTERN)?.[1] ?? null;
-        return version ? [version, tag.targetSha] : null;
+        return version ? [version, tag] : null;
       })
       .filter(Boolean)
   );
   const tags = windows
     .map((window) => {
       const targetCommit = window.commits.at(-1) ?? null;
-      const existingTargetSha = targetByVersion.get(window.version) ?? null;
+      const existingTag = existingTagByVersion.get(window.version) ?? null;
+      const existingTargetSha = existingTag?.targetSha ?? null;
       const windowCommitShas = new Set(window.commits.map((commit) => commit.sha));
 
       return {
         ...window,
-        tagName: window.version,
+        version: window.version,
+        tagName: existingTag?.tagName ?? formatVersionTag(window.version),
+        existingTagName: existingTag?.tagName ?? null,
         existingTargetSha,
         needsMove:
           existingTargetSha != null &&
@@ -394,7 +401,7 @@ export function selectReleaseTagsFromReleaseCommits(releaseCommits, existingTagN
     .filter((entry) => !taggedVersions.has(entry.version))
     .map(({ commit, version }) => ({
       version,
-      tagName: version,
+      tagName: formatVersionTag(version),
       startRef: commit.shortSha,
       endRef: commit.shortSha,
       targetSha: commit.sha,
@@ -827,10 +834,10 @@ export function executeReleaseTagPlan(plan, cwd) {
   try {
     for (const tag of plan.tags) {
       if (tag.needsMove) {
-        gitDeleteTag(tag.tagName, cwd);
+        gitDeleteTag(tag.existingTagName ?? tag.tagName, cwd);
       }
 
-      gitCreateAnnotatedTag(tag.tagName, tag.targetSha, `release ${tag.tagName}`, cwd);
+      gitCreateAnnotatedTag(tag.tagName, tag.targetSha, `release ${tag.version ?? tag.tagName.replace(/^v/, "")}`, cwd);
       createdTags.push(tag.tagName);
     }
   } catch (error) {

package/cli/services/pipelineService.js

@@ -5,6 +5,7 @@ import {
   readdirSync,
   writeFileSync
 } from "node:fs";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 const WORKFLOW_DIR = ".github/workflows";
@@ -64,6 +65,56 @@ function detectNodeVersion(cwd, packageJson) {
   };
 }
 
+function detectGitHubRepository(cwd) {
+  try {
+    const remote = execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+
+    const match =
+      remote.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/i) ??
+      remote.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/i);
+
+    if (!match) {
+      return null;
+    }
+
+    return {
+      owner: match[1],
+      repo: match[2],
+      slug: `${match[1]}/${match[2]}`
+    };
+  } catch {
+    return null;
+  }
+}
+
+function detectNodePackaging(cwd, packageJson) {
+  const packageName = (packageJson?.name ?? "package").replace(/^@[^/]+\//, "");
+  const githubRepository = detectGitHubRepository(cwd);
+  const homebrewFormulaPath = `packaging/homebrew-tap/Formula/${packageName}.rb`;
+
+  return {
+    deb: fileExists(cwd, "scripts/build-deb.sh"),
+    aur: fileExists(cwd, "packaging/aur/PKGBUILD"),
+    homebrew: fileExists(cwd, homebrewFormulaPath),
+    homebrewFormulaPath,
+    homebrewTapRepo: githubRepository ? `${githubRepository.owner}/homebrew-tap` : null,
+    githubRepository
+  };
+}
+
+function toHomebrewClassName(packageName) {
+  return packageName
+    .replace(/^@[^/]+\//, "")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+}
+
 function detectNodeProject(cwd) {
   if (!fileExists(cwd, "package.json")) {
     return null;
@@ -75,12 +126,14 @@ function detectNodeProject(cwd) {
   const packageManager = detectPackageManager(cwd);
   const releaseSupported = packageJson.private !== true && typeof packageJson.name === "string";
   const packSupported = packageJson.private !== true || Boolean(packageJson.bin);
+  const packaging = detectNodePackaging(cwd, packageJson);
 
   return {
     type: "node",
     displayName: packageJson.name || path.basename(cwd),
     packageManager,
     packageJson,
+    packaging,
     nodeVersion,
     commands: {
       install:
@@ -277,7 +330,9 @@ function buildNodeSetupStep(nodeVersion, packageManager = "npm") {
       "        uses: actions/setup-node@v4",
       "        with:",
       "          node-version-file: .nvmrc",
-      `          cache: ${packageManager}`
+      `          cache: ${packageManager}`,
+      "          registry-url: 'https://registry.npmjs.org'",
+      "          always-auth: true"
     ].join("\n");
   }
 
@@ -286,7 +341,9 @@ function buildNodeSetupStep(nodeVersion, packageManager = "npm") {
     "        uses: actions/setup-node@v4",
     "        with:",
     `          node-version: '${nodeVersion.value}'`,
-    `          cache: ${packageManager}`
+    `          cache: ${packageManager}`,
+    "          registry-url: 'https://registry.npmjs.org'",
+    "          always-auth: true"
   ].join("\n");
 }
 
@@ -440,8 +497,10 @@ export function inspectRepositoryForPipeline(cwd) {
       id: "ci-release",
       label: `CI plus ${primary.release.type} release automation`,
       description:
-        primary.type === "node"
-          ? "Publishes to npm when you push a version tag like v1.2.3."
+        primary.type === "node" && (primary.packaging?.deb || primary.packaging?.homebrew || primary.packaging?.aur)
+          ? "Publishes to npm on version tags, builds Debian packages, updates Homebrew when configured, and prints AUR update instructions."
+          : primary.type === "node"
+            ? "Publishes to npm when you push a version tag like v1.2.3."
           : primary.type === "python"
             ? "Builds and publishes to PyPI when you push a version tag like v1.2.3."
             : "Publishes to crates.io when you push a version tag like v1.2.3.",
@@ -569,16 +628,154 @@ export function buildReleaseWorkflow(context) {
   }
 
   if (context.type === "node") {
+    const packaging = context.packaging ?? {};
+    const githubRepository = packaging.githubRepository?.slug ?? null;
+    const homebrewTapRepo = packaging.homebrewTapRepo ?? null;
+    const packageName = context.packageJson?.name ?? context.displayName ?? "package";
+    const formulaClassName = toHomebrewClassName(packageName);
+    const binEntries = Object.entries(context.packageJson?.bin ?? {});
+    const executablePath = (binEntries[0]?.[1] ?? "cli/index.js").replace(/^\.\//, "");
+    const executableNames = binEntries.length > 0 ? binEntries.map(([name]) => name) : [packageName];
+
+    if (packaging.deb || packaging.homebrew || packaging.aur) {
+      return [
+        "name: Release",
+        "",
+        "on:",
+        "  push:",
+        "    tags:",
+        "      - 'v*'",
+        "",
+        "permissions:",
+        "  contents: write",
+        "",
+        "jobs:",
+        "  release:",
+        "    if: startsWith(github.ref_name, 'v')",
+        "    runs-on: ubuntu-latest",
+        "",
+        "    steps:",
+        "      - name: Checkout",
+        "        uses: actions/checkout@v4",
+        buildNodeReleaseSetup(context),
+        "      - name: Derive release metadata",
+        "        id: meta",
+        "        run: |",
+        "          VERSION=\"${GITHUB_REF_NAME#v}\"",
+        "          echo \"version=${VERSION}\" >> \"${GITHUB_OUTPUT}\"",
+        packaging.deb ? `          echo "deb_path=dist/${packageName}_\${VERSION}_all.deb" >> "\${GITHUB_OUTPUT}"` : "",
+        context.commands.test ? formatRunStep("Test", context.commands.test) : "",
+        context.commands.build ? formatRunStep("Build", context.commands.build) : "",
+        packaging.deb ? formatRunStep("Build Debian package", "./scripts/build-deb.sh") : "",
+        "      - name: Verify npm token",
+        "        env:",
+        "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
+        "        run: |",
+        "          if [ -z \"${NODE_AUTH_TOKEN}\" ]; then",
+        "            echo \"NPM_TOKEN is not configured for this repository.\"",
+        "            echo \"Add it in GitHub: Settings -> Secrets and variables -> Actions -> New repository secret.\"",
+        "            exit 1",
+        "          fi",
+        "          printf \"//registry.npmjs.org/:_authToken=%s\\n\" \"${NODE_AUTH_TOKEN}\" > \"${HOME}/.npmrc\"",
+        "          npm whoami",
+        "      - name: Publish to npm",
+        "        env:",
+        "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
+        "        run: npm publish",
+        "      - name: Compute npm tarball SHA-256",
+        "        id: npm",
+        "        run: |",
+        "          VERSION=\"${{ steps.meta.outputs.version }}\"",
+        `          TARBALL_URL="https://registry.npmjs.org/${packageName}/-/${packageName}-\${VERSION}.tgz"`,
+        `          curl -fsSL "\${TARBALL_URL}" -o "${packageName}-\${VERSION}.tgz"`,
+        `          SHA256="$(sha256sum "${packageName}-\${VERSION}.tgz" | awk '{print $1}')"`,
+        "          echo \"tarball_url=${TARBALL_URL}\" >> \"${GITHUB_OUTPUT}\"",
+        "          echo \"sha256=${SHA256}\" >> \"${GITHUB_OUTPUT}\"",
+        packaging.homebrew && homebrewTapRepo
+          ? [
+              "      - name: Checkout Homebrew tap",
+              "        uses: actions/checkout@v4",
+              "        with:",
+              `          repository: ${homebrewTapRepo}`,
+              "          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}",
+              "          path: homebrew-tap",
+              "      - name: Update Homebrew formula",
+              "        run: |",
+              "          VERSION=\"${{ steps.meta.outputs.version }}\"",
+              "          SHA256=\"${{ steps.npm.outputs.sha256 }}\"",
+              `          FORMULA_PATH="homebrew-tap/Formula/${packageName}.rb"`,
+              "          mkdir -p \"$(dirname \"${FORMULA_PATH}\")\"",
+              "          cat > \"${FORMULA_PATH}\" <<EOF",
+              `          class ${formulaClassName} < Formula`,
+              `            desc ${JSON.stringify(context.packageJson?.description ?? "")}`,
+              `            homepage ${JSON.stringify(githubRepository ? `https://github.com/${githubRepository}` : "")}`,
+              `            url "https://registry.npmjs.org/${packageName}/-/${packageName}-${"${VERSION}"}.tgz"`,
+              "            sha256 \"${SHA256}\"",
+              `            license ${JSON.stringify(context.packageJson?.license ?? "MIT")}`,
+              "",
+              "            depends_on \"node\"",
+              "",
+              "            def install",
+              "              libexec.install Dir[\"package/*\"]",
+              ...executableNames.map((name) => `              bin.install_symlink libexec/"${executablePath}" => "${name}"`),
+              "            end",
+              "",
+              "            test do",
+              `              assert_match ${JSON.stringify(executableNames[0])}, shell_output("#{bin}/${executableNames[0]} --help")`,
+              "            end",
+              "          end",
+              "          EOF",
+              "      - name: Commit and push Homebrew tap changes",
+              "        working-directory: homebrew-tap",
+              "        run: |",
+              "          git config user.name \"github-actions[bot]\"",
+              "          git config user.email \"41898282+github-actions[bot]@users.noreply.github.com\"",
+              `          git add Formula/${packageName}.rb`,
+              "          if git diff --cached --quiet; then",
+              "            echo \"No Homebrew formula changes to commit.\"",
+              "            exit 0",
+              "          fi",
+              "          git commit -m \"gitxplain ${GITHUB_REF_NAME}\"",
+              "          git push"
+            ].join("\n")
+          : "",
+        packaging.deb
+          ? [
+              "      - name: Create GitHub release and upload Debian package",
+              "        uses: softprops/action-gh-release@v2",
+              "        with:",
+              "          files: ${{ steps.meta.outputs.deb_path }}"
+            ].join("\n")
+          : "",
+        packaging.aur
+          ? [
+              "      - name: Print AUR update instructions",
+              "        run: |",
+              "          VERSION=\"${{ steps.meta.outputs.version }}\"",
+              "          SHA256=\"${{ steps.npm.outputs.sha256 }}\"",
+              "          echo \"Manual AUR update steps:\"",
+              "          echo \"1. Update packaging/aur/PKGBUILD with pkgver=${VERSION} and sha256sums=('${SHA256}').\"",
+              "          echo \"2. Run: makepkg --printsrcinfo > .SRCINFO\"",
+              "          echo \"3. Commit PKGBUILD and .SRCINFO to the AUR git repository and push.\""
+            ].join("\n")
+          : ""
+      ]
+        .filter(Boolean)
+        .join("\n")
+        .concat("\n");
+    }
+
     return [
       "name: Release",
       "",
       "on:",
       "  push:",
       "    tags:",
-      "      - 'v*.*.*'",
+      "      - 'v*'",
       "",
       "jobs:",
       "  publish:",
+      "    if: startsWith(github.ref_name, 'v')",
       "    runs-on: ubuntu-latest",
       "    permissions:",
       "      contents: read",
@@ -588,6 +785,17 @@ export function buildReleaseWorkflow(context) {
       buildNodeReleaseSetup(context),
       context.commands.test ? formatRunStep("Test", context.commands.test) : "",
       context.commands.build ? formatRunStep("Build", context.commands.build) : "",
+      "      - name: Verify npm token",
+      "        env:",
+      "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
+      "        run: |",
+      "          if [ -z \"${NODE_AUTH_TOKEN}\" ]; then",
+      "            echo \"NPM_TOKEN is not configured for this repository.\"",
+      "            echo \"Add it in GitHub: Settings -> Secrets and variables -> Actions -> New repository secret.\"",
+      "            exit 1",
+      "          fi",
+      "          printf \"//registry.npmjs.org/:_authToken=%s\\n\" \"${NODE_AUTH_TOKEN}\" > \"${HOME}/.npmrc\"",
+      "          npm whoami",
       "      - name: Publish to npm",
       "        env:",
       "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
@@ -605,7 +813,7 @@ export function buildReleaseWorkflow(context) {
       "on:",
       "  push:",
       "    tags:",
-      "      - 'v*.*.*'",
+      "      - 'v*'",
       "",
       "jobs:",
       "  publish:",
@@ -635,10 +843,11 @@ export function buildReleaseWorkflow(context) {
     "on:",
     "  push:",
     "    tags:",
-    "      - 'v*.*.*'",
+    "      - 'v*'",
     "",
     "jobs:",
     "  publish:",
+    "    if: startsWith(github.ref_name, 'v')",
     "    runs-on: ubuntu-latest",
     "    steps:",
     "      - name: Checkout",
@@ -660,7 +869,7 @@ export function buildContainerWorkflow() {
     "  push:",
     "    branches: [main, master]",
     "    tags:",
-    "      - 'v*.*.*'",
+    "      - 'v*'",
     "  pull_request:",
     "",
     "jobs:",
@@ -784,13 +993,21 @@ export function writePipelineFiles(cwd, analysis, selection) {
   mkdirSync(workflowDir, { recursive: true });
 
   const writtenFiles = [];
+  const updatedFiles = [];
+  const unchangedFiles = [];
   const notes = [];
 
   const writeWorkflow = (relativePath, contents) => {
     const absolutePath = path.join(cwd, relativePath);
     mkdirSync(path.dirname(absolutePath), { recursive: true });
+    const existingContents = existsSync(absolutePath) ? readFileSync(absolutePath, "utf8") : null;
     writeFileSync(absolutePath, contents, "utf8");
     writtenFiles.push(relativePath);
+    if (existingContents === contents) {
+      unchangedFiles.push(relativePath);
+    } else {
+      updatedFiles.push(relativePath);
+    }
   };
 
   if (selection.id === "ci" || selection.id === "ci-release") {
@@ -802,6 +1019,12 @@ export function writePipelineFiles(cwd, analysis, selection) {
 
     if (analysis.primary.release.type === "npm") {
       notes.push("Add an `NPM_TOKEN` repository secret before pushing a release tag.");
+      if (analysis.primary.packaging?.homebrew) {
+        notes.push("Add a `HOMEBREW_TAP_TOKEN` repository secret so CI can update your tap repository.");
+      }
+      if (analysis.primary.packaging?.aur) {
+        notes.push("AUR updates are still manual. The generated release workflow prints the exact PKGBUILD and .SRCINFO refresh steps.");
+      }
     } else if (analysis.primary.release.type === "pypi") {
       notes.push("Add a `PYPI_TOKEN` repository secret before pushing a release tag.");
     } else if (analysis.primary.release.type === "crates") {
@@ -829,5 +1052,5 @@ export function writePipelineFiles(cwd, analysis, selection) {
     notes.push("This option only creates the container workflow. Run `gitxplain --pipeline` again if you also want CI verification.");
   }
 
-  return { writtenFiles, notes };
+  return { writtenFiles, updatedFiles, unchangedFiles, notes };
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "gitxplain",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "AI-powered Git commit explainer CLI",
   "type": "module",
   "bin": {
-    "gitxplain": "./cli/index.js",
-    "gitxplore": "./cli/index.js"
+    "gitxplain": "cli/index.js",
+    "gitxplore": "cli/index.js"
   },
   "scripts": {
     "start": "node ./cli/index.js",

package/packaging/README.md

@@ -0,0 +1,60 @@
+# Packaging
+
+This directory contains packaging assets for Homebrew, AUR, and Debian releases.
+
+## Homebrew tap
+
+Template formula: `packaging/homebrew-tap/Formula/gitxplain.rb`
+
+Create and publish the tap repository:
+
+```bash
+gh repo create guruswarupa/homebrew-tap --public --clone
+cd homebrew-tap
+mkdir -p Formula
+cp /path/to/gitxplain/packaging/homebrew-tap/Formula/gitxplain.rb Formula/gitxplain.rb
+git add Formula/gitxplain.rb
+git commit -m "Add gitxplain formula"
+git push -u origin main
+```
+
+After each new npm publish, update the formula `url` and replace `"<SHA256_PLACEHOLDER>"` with the tarball SHA-256, then push the change.
+
+## AUR
+
+Template files:
+
+- `packaging/aur/PKGBUILD`
+- `packaging/aur/.SRCINFO`
+
+Generate `.SRCINFO` after updating `PKGBUILD`:
+
+```bash
+cd /path/to/gitxplain/packaging/aur
+makepkg --printsrcinfo > .SRCINFO
+```
+
+Create and publish the AUR package:
+
+```bash
+git clone ssh://aur@aur.archlinux.org/gitxplain.git aur-gitxplain
+cd aur-gitxplain
+cp /path/to/gitxplain/packaging/aur/PKGBUILD .
+cp /path/to/gitxplain/packaging/aur/.SRCINFO .
+makepkg --printsrcinfo > .SRCINFO
+git add PKGBUILD .SRCINFO
+git commit -m "Initial gitxplain release"
+git push
+```
+
+Replace `"<SHA256_PLACEHOLDER>"` with the npm tarball SHA-256 before publishing.
+
+## Debian
+
+Build the Debian package from this repository:
+
+```bash
+./scripts/build-deb.sh
+```
+
+The package is written to `dist/gitxplain_<version>_all.deb`.

package/packaging/aur/.SRCINFO

@@ -0,0 +1,12 @@
+pkgbase = gitxplain
+	pkgdesc = AI-powered Git commit explainer CLI
+	pkgver = 0.1.9
+	pkgrel = 1
+	url = https://github.com/guruswarupa/gitxplain
+	arch = any
+	license = MIT
+	depends = nodejs
+	source = https://registry.npmjs.org/gitxplain/-/gitxplain-0.1.9.tgz
+	sha256sums = <SHA256_PLACEHOLDER>
+
+pkgname = gitxplain

package/packaging/aur/PKGBUILD

@@ -0,0 +1,22 @@
+pkgname=gitxplain
+pkgver=0.1.9
+pkgrel=1
+pkgdesc="AI-powered Git commit explainer CLI"
+arch=('any')
+url="https://github.com/guruswarupa/gitxplain"
+license=('MIT')
+depends=('nodejs')
+source=("https://registry.npmjs.org/${pkgname}/-/${pkgname}-${pkgver}.tgz")
+sha256sums=('<SHA256_PLACEHOLDER>')
+
+package() {
+  install -d "${pkgdir}/usr/lib/${pkgname}"
+  tar -xzf "${srcdir}/${pkgname}-${pkgver}.tgz" -C "${srcdir}"
+  cp -a "${srcdir}/package/." "${pkgdir}/usr/lib/${pkgname}/"
+
+  chmod 755 "${pkgdir}/usr/lib/${pkgname}/cli/index.js"
+
+  install -d "${pkgdir}/usr/bin"
+  ln -sf "/usr/lib/${pkgname}/cli/index.js" "${pkgdir}/usr/bin/gitxplain"
+  ln -sf "/usr/lib/${pkgname}/cli/index.js" "${pkgdir}/usr/bin/gitxplore"
+}

package/packaging/homebrew-tap/Formula/gitxplain.rb

@@ -0,0 +1,19 @@
+class Gitxplain < Formula
+  desc "AI-powered Git commit explainer CLI"
+  homepage "https://github.com/guruswarupa/gitxplain"
+  url "https://registry.npmjs.org/gitxplain/-/gitxplain-0.1.9.tgz"
+  sha256 "<SHA256_PLACEHOLDER>"
+  license "MIT"
+
+  depends_on "node"
+
+  def install
+    libexec.install Dir["package/*"]
+    bin.install_symlink libexec/"cli/index.js" => "gitxplain"
+    bin.install_symlink libexec/"cli/index.js" => "gitxplore"
+  end
+
+  test do
+    assert_match "gitxplain", shell_output("#{bin}/gitxplain --help")
+  end
+end

package/scripts/build-deb.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PACKAGE_JSON="${ROOT_DIR}/package.json"
+VERSION="$(node -p "JSON.parse(require('node:fs').readFileSync(process.argv[1], 'utf8')).version" "${PACKAGE_JSON}")"
+DESCRIPTION="$(node -p "JSON.parse(require('node:fs').readFileSync(process.argv[1], 'utf8')).description" "${PACKAGE_JSON}")"
+PACKAGE_NAME="gitxplain"
+ARCHITECTURE="${DEB_ARCHITECTURE:-all}"
+MAINTAINER="${DEB_MAINTAINER:-Guruswarupa <opensource@local.invalid>}"
+OUTPUT_DIR="${ROOT_DIR}/dist"
+BUILD_ROOT="$(mktemp -d)"
+PACKAGE_ROOT="${BUILD_ROOT}/${PACKAGE_NAME}_${VERSION}"
+INSTALL_ROOT="${PACKAGE_ROOT}/usr/lib/${PACKAGE_NAME}"
+CONTROL_DIR="${PACKAGE_ROOT}/DEBIAN"
+DOC_DIR="${PACKAGE_ROOT}/usr/share/doc/${PACKAGE_NAME}"
+DEB_FILE="${OUTPUT_DIR}/${PACKAGE_NAME}_${VERSION}_${ARCHITECTURE}.deb"
+
+cleanup() {
+  rm -rf "${BUILD_ROOT}"
+}
+
+trap cleanup EXIT
+
+mkdir -p "${OUTPUT_DIR}" "${INSTALL_ROOT}" "${CONTROL_DIR}" "${DOC_DIR}" "${PACKAGE_ROOT}/usr/bin"
+
+cp -a \
+  "${ROOT_DIR}/cli" \
+  "${ROOT_DIR}/prompts" \
+  "${ROOT_DIR}/package.json" \
+  "${ROOT_DIR}/README.md" \
+  "${INSTALL_ROOT}/"
+
+find "${PACKAGE_ROOT}" -type d -exec chmod 755 {} +
+find "${PACKAGE_ROOT}" -type f -exec chmod 644 {} +
+chmod 755 "${INSTALL_ROOT}/cli/index.js"
+ln -s "../lib/${PACKAGE_NAME}/cli/index.js" "${PACKAGE_ROOT}/usr/bin/gitxplain"
+ln -s "../lib/${PACKAGE_NAME}/cli/index.js" "${PACKAGE_ROOT}/usr/bin/gitxplore"
+
+cat > "${CONTROL_DIR}/control" <<EOF
+Package: ${PACKAGE_NAME}
+Version: ${VERSION}
+Section: utils
+Priority: optional
+Architecture: ${ARCHITECTURE}
+Maintainer: ${MAINTAINER}
+Depends: nodejs (>= 18)
+Homepage: https://github.com/guruswarupa/gitxplain
+Description: ${DESCRIPTION}
+ AI-powered Git commit explainer CLI distributed as a Debian package.
+EOF
+
+cat > "${DOC_DIR}/copyright" <<EOF
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: gitxplain
+Source: https://github.com/guruswarupa/gitxplain
+
+Files: *
+License: MIT
+EOF
+
+dpkg-deb --root-owner-group --build "${PACKAGE_ROOT}" "${DEB_FILE}" >/dev/null
+echo "${DEB_FILE}"