gitxplain 0.1.8 → 0.2.0

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");
 }
 
@@ -414,6 +471,24 @@ export function inspectRepositoryForPipeline(cwd) {
       label: "GitHub Actions CI verification",
       description: "Runs install, lint, test, build, and package checks when supported.",
       files: [".github/workflows/ci.yml"]
+    },
+    {
+      id: "gitlab-ci",
+      label: "GitLab CI verification",
+      description: "Creates a .gitlab-ci.yml pipeline with install, lint, test, and build stages.",
+      files: [".gitlab-ci.yml"]
+    },
+    {
+      id: "circleci",
+      label: "CircleCI verification",
+      description: "Creates a .circleci/config.yml pipeline for verification jobs.",
+      files: [".circleci/config.yml"]
+    },
+    {
+      id: "bitbucket-pipelines",
+      label: "Bitbucket Pipelines verification",
+      description: "Creates bitbucket-pipelines.yml with install, test, and build steps.",
+      files: ["bitbucket-pipelines.yml"]
     }
   ];
 
@@ -422,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.",
@@ -551,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",
@@ -570,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 }}",
@@ -587,7 +813,7 @@ export function buildReleaseWorkflow(context) {
       "on:",
       "  push:",
       "    tags:",
-      "      - 'v*.*.*'",
+      "      - 'v*'",
       "",
       "jobs:",
       "  publish:",
@@ -617,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",
@@ -642,7 +869,7 @@ export function buildContainerWorkflow() {
     "  push:",
     "    branches: [main, master]",
     "    tags:",
-    "      - 'v*.*.*'",
+    "      - 'v*'",
     "  pull_request:",
     "",
     "jobs:",
@@ -676,6 +903,87 @@ export function buildContainerWorkflow() {
   ].join("\n").concat("\n");
 }
 
+function buildPipelineCommands(context) {
+  return [context.commands.install, context.commands.lint, context.commands.test, context.commands.build, context.commands.pack]
+    .filter(Boolean);
+}
+
+export function buildGitLabCiWorkflow(context) {
+  const commands = buildPipelineCommands(context);
+  const image =
+    context.type === "python"
+      ? "python:3.12"
+      : context.type === "go"
+        ? "golang:1.22"
+        : context.type === "rust"
+          ? "rust:latest"
+          : "node:20";
+
+  return [
+    `image: ${image}`,
+    "",
+    "stages:",
+    "  - verify",
+    "",
+    "verify:",
+    "  stage: verify",
+    "  script:",
+    ...commands.map((command) => `    - ${command}`)
+  ].join("\n").concat("\n");
+}
+
+export function buildCircleCiWorkflow(context) {
+  const image =
+    context.type === "python"
+      ? "cimg/python:3.12"
+      : context.type === "go"
+        ? "cimg/go:1.22"
+        : context.type === "rust"
+          ? "cimg/rust:1.83"
+          : "cimg/node:20.10";
+  const commands = buildPipelineCommands(context);
+
+  return [
+    "version: 2.1",
+    "",
+    "jobs:",
+    "  verify:",
+    "    docker:",
+    `      - image: ${image}`,
+    "    steps:",
+    "      - checkout",
+    ...commands.map((command) => `      - run: ${command}`),
+    "",
+    "workflows:",
+    "  verify:",
+    "    jobs:",
+    "      - verify"
+  ].join("\n").concat("\n");
+}
+
+export function buildBitbucketPipelinesWorkflow(context) {
+  const image =
+    context.type === "python"
+      ? "python:3.12"
+      : context.type === "go"
+        ? "golang:1.22"
+        : context.type === "rust"
+          ? "rust:latest"
+          : "node:20";
+  const commands = buildPipelineCommands(context);
+
+  return [
+    `image: ${image}`,
+    "",
+    "pipelines:",
+    "  default:",
+    "    - step:",
+    "        name: Verify",
+    "        script:",
+    ...commands.map((command) => `          - ${command}`)
+  ].join("\n").concat("\n");
+}
+
 export function writePipelineFiles(cwd, analysis, selection) {
   if (!analysis.supported) {
     throw new Error(analysis.reason);
@@ -685,12 +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") {
@@ -702,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") {
@@ -713,9 +1036,21 @@ export function writePipelineFiles(cwd, analysis, selection) {
     writeWorkflow(".github/workflows/container.yml", buildContainerWorkflow());
   }
 
+  if (selection.id === "gitlab-ci") {
+    writeWorkflow(".gitlab-ci.yml", buildGitLabCiWorkflow(analysis.primary));
+  }
+
+  if (selection.id === "circleci") {
+    writeWorkflow(".circleci/config.yml", buildCircleCiWorkflow(analysis.primary));
+  }
+
+  if (selection.id === "bitbucket-pipelines") {
+    writeWorkflow("bitbucket-pipelines.yml", buildBitbucketPipelinesWorkflow(analysis.primary));
+  }
+
   if (selection.id === "container" && !selection.files.includes(".github/workflows/ci.yml")) {
     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/cli/services/promptService.js

@@ -16,7 +16,14 @@ const PROMPT_FILES = {
   review: "review.txt",
   security: "security.txt",
   split: "split.txt",
-  commit: "commit.txt"
+  commit: "commit.txt",
+  changelog: "changelog.txt",
+  refactor: "refactor.txt",
+  "test-suggest": "test-suggest.txt",
+  "pr-description": "pr-description.txt",
+  blame: "blame.txt",
+  stash: "stash.txt",
+  conflict: "conflict.txt"
 };
 
 function fillTemplate(template, values) {

package/cli/services/splitService.js

@@ -1,4 +1,3 @@
-import process from "node:process";
 import {
   createCommitFromTree,
   deletePaths,
@@ -32,26 +31,7 @@ import {
   runGitCommandUnchecked,
   resolveCommitSha
 } from "./gitService.js";
-
-const ANSI = {
-  reset: "\u001b[0m",
-  bold: "\u001b[1m",
-  cyan: "\u001b[36m",
-  yellow: "\u001b[33m",
-  green: "\u001b[32m"
-};
-
-function supportsColor() {
-  return Boolean(process.stdout?.isTTY) && process.env.NO_COLOR == null;
-}
-
-function colorize(text, color) {
-  if (!supportsColor()) {
-    return text;
-  }
-
-  return `${color}${text}${ANSI.reset}`;
-}
+import { ANSI, colorize } from "./colorSupport.js";
 
 function extractJsonPayload(explanation) {
   const fencedMatch = explanation.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);

package/cli/services/usageService.js

@@ -0,0 +1,158 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function getUsageLogPath() {
+  return path.join(os.homedir(), ".gitxplain", "usage.jsonl");
+}
+
+export function getUsageLogFile() {
+  return getUsageLogPath();
+}
+
+function readRecords() {
+  const filePath = getUsageLogPath();
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  return readFileSync(filePath, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function parseNumeric(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+export function normalizeUsageMetrics(usage) {
+  if (!usage || typeof usage !== "object") {
+    return {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0
+    };
+  }
+
+  const inputTokens =
+    parseNumeric(usage.prompt_tokens) ||
+    parseNumeric(usage.input_tokens) ||
+    parseNumeric(usage.promptTokenCount);
+  const outputTokens =
+    parseNumeric(usage.completion_tokens) ||
+    parseNumeric(usage.output_tokens) ||
+    parseNumeric(usage.candidatesTokenCount);
+  const totalTokens =
+    parseNumeric(usage.total_tokens) ||
+    parseNumeric(usage.totalTokenCount) ||
+    inputTokens + outputTokens;
+
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens
+  };
+}
+
+function parseEnvPrice(envKey) {
+  const raw = process.env[envKey];
+  if (raw == null || raw === "") {
+    return null;
+  }
+
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+export function resolvePricing(config) {
+  const providerKey = config.provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  const modelKey = String(config.model ?? "default").toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+
+  const inputPerMillion =
+    parseEnvPrice(`${providerKey}_${modelKey}_INPUT_COST_PER_MTOK`) ??
+    parseEnvPrice(`${providerKey}_INPUT_COST_PER_MTOK`) ??
+    parseEnvPrice("LLM_INPUT_COST_PER_MTOK");
+  const outputPerMillion =
+    parseEnvPrice(`${providerKey}_${modelKey}_OUTPUT_COST_PER_MTOK`) ??
+    parseEnvPrice(`${providerKey}_OUTPUT_COST_PER_MTOK`) ??
+    parseEnvPrice("LLM_OUTPUT_COST_PER_MTOK");
+
+  if (inputPerMillion == null || outputPerMillion == null) {
+    return null;
+  }
+
+  return {
+    inputPerMillion,
+    outputPerMillion
+  };
+}
+
+export function estimateCostUsd(usage, pricing) {
+  if (!pricing) {
+    return null;
+  }
+
+  const metrics = normalizeUsageMetrics(usage);
+  const costUsd =
+    (metrics.inputTokens / 1_000_000) * pricing.inputPerMillion +
+    (metrics.outputTokens / 1_000_000) * pricing.outputPerMillion;
+
+  return Number.isFinite(costUsd) ? costUsd : null;
+}
+
+export function appendUsageRecord({ provider, model, usage, latencyMs, estimatedCostUsd }) {
+  const metrics = normalizeUsageMetrics(usage);
+  if (metrics.totalTokens === 0 && estimatedCostUsd == null) {
+    return;
+  }
+
+  const filePath = getUsageLogPath();
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  appendFileSync(
+    filePath,
+    `${JSON.stringify({
+      timestamp: new Date().toISOString(),
+      provider,
+      model,
+      usage: metrics,
+      latencyMs: latencyMs ?? null,
+      estimatedCostUsd
+    })}\n`,
+    "utf8"
+  );
+}
+
+export function getUsageStats() {
+  const records = readRecords();
+
+  return records.reduce(
+    (summary, record) => {
+      summary.requestCount += 1;
+      summary.inputTokens += parseNumeric(record.usage?.inputTokens);
+      summary.outputTokens += parseNumeric(record.usage?.outputTokens);
+      summary.totalTokens += parseNumeric(record.usage?.totalTokens);
+      summary.estimatedCostUsd += parseNumeric(record.estimatedCostUsd);
+      return summary;
+    },
+    {
+      requestCount: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      estimatedCostUsd: 0
+    }
+  );
+}
+
+export function clearUsageLog() {
+  const filePath = getUsageLogPath();
+  const count = readRecords().length;
+
+  if (existsSync(filePath)) {
+    rmSync(filePath, { force: true });
+  }
+
+  return count;
+}