@qodly/gentrace 0.1.0

package/dist/lib/debug.js

@@ -0,0 +1,36 @@
+/** CLI / GENTRACE_DEBUG verbose logging (stderr). */
+let enabledOverride = false;
+function envDebug() {
+    const v = process.env.GENTRACE_DEBUG?.toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+export const VERBOSE_FLAGS = new Set(['--verbose', '--debug', '-v']);
+export function isDebug() {
+    return enabledOverride || envDebug();
+}
+export function enableDebug() {
+    enabledOverride = true;
+}
+/** Remove --verbose / --debug / -v from argv; enables debug if any were present. */
+export function parseVerboseFlags(argv) {
+    const out = [];
+    for (const a of argv) {
+        if (VERBOSE_FLAGS.has(a)) {
+            enableDebug();
+        }
+        else {
+            out.push(a);
+        }
+    }
+    return out;
+}
+export function debugLog(...parts) {
+    if (!isDebug())
+        return;
+    console.error('[gentrace]', ...parts);
+}
+export function redactApiKey(key) {
+    if (key.length <= 8)
+        return '***';
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}

package/dist/lib/exec.d.ts

@@ -0,0 +1,14 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function exec(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeout?: number;
+}): Promise<ExecResult>;
+export declare function execOrThrow(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeout?: number;
+}): Promise<ExecResult>;
+export declare function which(binary: string): Promise<string | null>;

package/dist/lib/exec.js

@@ -0,0 +1,26 @@
+import { execFile } from 'node:child_process';
+export function exec(cmd, args, opts) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, {
+            cwd: opts?.cwd,
+            timeout: opts?.timeout ?? 30_000,
+            maxBuffer: 4 * 1024 * 1024,
+            encoding: 'utf-8',
+        }, (error, stdout, stderr) => {
+            const exitCode = error && 'code' in error && typeof error.code === 'number' ? error.code : error ? 1 : 0;
+            resolve({ stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
+        });
+    });
+}
+export function execOrThrow(cmd, args, opts) {
+    return exec(cmd, args, opts).then((r) => {
+        if (r.exitCode !== 0) {
+            throw new Error(`${cmd} ${args.join(' ')} exited ${r.exitCode}: ${r.stderr || r.stdout}`);
+        }
+        return r;
+    });
+}
+export async function which(binary) {
+    const r = await exec('which', [binary]);
+    return r.exitCode === 0 ? r.stdout.trim() : null;
+}

package/dist/lib/git-ai-ingest-context.d.ts

@@ -0,0 +1,23 @@
+import type { GitAiStats } from './git-ai.js';
+/** Pick the tool/model bucket with the most AI-attributed lines (git-ai `tool_model_breakdown`). */
+export declare function primaryToolModelKey(stats: GitAiStats | null): string | undefined;
+/** git-ai uses `tool::model` (e.g. `cursor::default`) or legacy `tool/model`. */
+export declare function parseToolModelKey(key: string): {
+    tool: string;
+    model: string | undefined;
+};
+/** Read agent tool from `git-ai diff --json` when stats are not yet populated. */
+export declare function toolModelFromDiff(diff: unknown): {
+    tool: string;
+    model: string | undefined;
+} | null;
+/**
+ * Map git-ai agent `tool` slug to Gentrace telemetry `ide` (see shared-types `IDE` enum names).
+ * Falls back to `cli` when attribution is CLI-only or unknown.
+ */
+export declare function inferIdeFromAgentTool(tool: string): string;
+export declare function resolvePublishAiContext(stats: GitAiStats | null, diff: unknown): {
+    aiProvider: string;
+    aiModel: string | undefined;
+    ide: string;
+};

package/dist/lib/git-ai-ingest-context.js

@@ -0,0 +1,81 @@
+/** Pick the tool/model bucket with the most AI-attributed lines (git-ai `tool_model_breakdown`). */
+export function primaryToolModelKey(stats) {
+    if (!stats?.tool_model_breakdown)
+        return undefined;
+    const entries = Object.entries(stats.tool_model_breakdown);
+    if (entries.length === 0)
+        return undefined;
+    entries.sort((a, b) => {
+        const aiA = a[1]?.ai_additions ?? 0;
+        const aiB = b[1]?.ai_additions ?? 0;
+        return aiB - aiA;
+    });
+    return entries[0]?.[0];
+}
+/** git-ai uses `tool::model` (e.g. `cursor::default`) or legacy `tool/model`. */
+export function parseToolModelKey(key) {
+    const k = key.trim();
+    if (!k)
+        return { tool: 'custom', model: undefined };
+    if (k.includes('::')) {
+        const [a, b] = k.split('::');
+        const tool = (a ?? '').trim() || 'custom';
+        const model = (b ?? '').trim() || undefined;
+        return { tool, model };
+    }
+    if (k.includes('/')) {
+        const [a, b] = k.split('/');
+        const tool = (a ?? '').trim() || 'custom';
+        const model = (b ?? '').trim() || undefined;
+        return { tool, model };
+    }
+    return { tool: k, model: undefined };
+}
+/** Read agent tool from `git-ai diff --json` when stats are not yet populated. */
+export function toolModelFromDiff(diff) {
+    if (!diff || typeof diff !== 'object')
+        return null;
+    const d = diff;
+    if (!d.sessions || typeof d.sessions !== 'object')
+        return null;
+    for (const s of Object.values(d.sessions)) {
+        const tool = s?.agent_id?.tool?.trim();
+        if (!tool)
+            continue;
+        const rawModel = s?.agent_id?.model?.trim();
+        const model = rawModel && rawModel.length > 0 ? rawModel : undefined;
+        return { tool, model };
+    }
+    return null;
+}
+/**
+ * Map git-ai agent `tool` slug to Gentrace telemetry `ide` (see shared-types `IDE` enum names).
+ * Falls back to `cli` when attribution is CLI-only or unknown.
+ */
+export function inferIdeFromAgentTool(tool) {
+    const t = tool.toLowerCase().trim();
+    if (!t || t === 'custom')
+        return 'cli';
+    if (t === 'cursor')
+        return 'cursor_ide';
+    if (t === 'vscode' || t === 'code' || t === 'codespaces')
+        return 'vscode';
+    if (t === 'jetbrains' || t === 'idea' || t === 'intellij' || t === 'webstorm' || t === 'pycharm')
+        return 'jetbrains';
+    if (t === 'neovim' || t === 'nvim')
+        return 'neovim';
+    if (t === 'zed')
+        return 'zed';
+    return t;
+}
+export function resolvePublishAiContext(stats, diff) {
+    const fromKey = primaryToolModelKey(stats);
+    const parsedFromStats = fromKey ? parseToolModelKey(fromKey) : null;
+    const parsedFromDiff = toolModelFromDiff(diff);
+    const merged = parsedFromStats ?? parsedFromDiff ?? { tool: 'custom', model: undefined };
+    return {
+        aiProvider: merged.tool,
+        aiModel: merged.model,
+        ide: inferIdeFromAgentTool(merged.tool),
+    };
+}

package/dist/lib/git-ai.d.ts

@@ -0,0 +1,35 @@
+export declare function isGitAiInstalled(): Promise<boolean>;
+export declare function getGitAiVersion(): Promise<string | null>;
+export interface GitAiStats {
+    human_additions: number;
+    ai_additions: number;
+    ai_accepted: number;
+    mixed_additions: number;
+    /** Lines not yet classified; git-ai keeps additions here until authorship is bound (common right after commit). */
+    unknown_additions?: number;
+    git_diff_added_lines: number;
+    git_diff_deleted_lines: number;
+    total_ai_additions: number;
+    total_ai_deletions: number;
+    time_waiting_for_ai: number;
+    tool_model_breakdown: Record<string, {
+        ai_additions: number;
+        ai_accepted: number;
+        mixed_additions?: number;
+        total_ai_additions?: number;
+        total_ai_deletions?: number;
+        time_waiting_for_ai?: number;
+    }>;
+}
+export declare function getStats(cwd: string, ref?: string): Promise<GitAiStats | null>;
+/**
+ * After `post-commit`, git-ai stats and `git-ai show` can lag behind the commit.
+ * Poll both until attribution is reflected (or timeout), then return the last stats snapshot.
+ */
+export declare function waitForGitAiStats(cwd: string, ref: string, commitInsertions: number, opts?: {
+    maxWaitMs?: number;
+    pollMs?: number;
+}): Promise<GitAiStats | null>;
+export declare function getDiff(cwd: string, ref?: string): Promise<unknown | null>;
+export declare function getShow(cwd: string, ref?: string): Promise<string | null>;
+export declare function getPrompt(cwd: string, promptId: string, commitRef?: string): Promise<unknown | null>;

package/dist/lib/git-ai.js

@@ -0,0 +1,105 @@
+import { exec, which } from './exec.js';
+export async function isGitAiInstalled() {
+    return (await which('git-ai')) !== null;
+}
+export async function getGitAiVersion() {
+    const r = await exec('git-ai', ['--version']);
+    return r.exitCode === 0 ? r.stdout.trim() : null;
+}
+export async function getStats(cwd, ref = 'HEAD') {
+    const r = await exec('git-ai', ['stats', ref, '--json'], { cwd, timeout: 15_000 });
+    if (r.exitCode !== 0)
+        return null;
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * True when git-ai has finished classifying insertions for this commit (or there is nothing to classify).
+ *
+ * git-ai can briefly expose inconsistent snapshots (e.g. `unknown_additions` only, or all counters at 0 while
+ * `git_diff_added_lines` > 0). We wait until at least one attributed bucket or `tool_model_breakdown` is set.
+ */
+function statsLookReady(stats, commitInsertions) {
+    if (!stats)
+        return false;
+    const attributed = stats.ai_additions + stats.human_additions + stats.mixed_additions;
+    const hasBreakdown = Object.keys(stats.tool_model_breakdown ?? {}).length > 0;
+    const diffAdds = Math.max(0, Number(stats.git_diff_added_lines) || 0);
+    const hasInsertionsToAttribute = diffAdds > 0 || commitInsertions > 0;
+    if (!hasInsertionsToAttribute)
+        return true;
+    return attributed > 0 || hasBreakdown;
+}
+const NO_AUTHORSHIP_PLACEHOLDER = /no authorship data found/i;
+/** Stats counters look usable; see also `publishDataReady` for git-ai `show` alignment. */
+function publishDataReady(stats, show, commitInsertions) {
+    if (!statsLookReady(stats, commitInsertions))
+        return false;
+    if (!stats)
+        return false;
+    const attributed = stats.ai_additions + stats.human_additions + stats.mixed_additions;
+    const hasBreakdown = Object.keys(stats.tool_model_breakdown ?? {}).length > 0;
+    const diffAdds = Math.max(0, Number(stats.git_diff_added_lines) || 0);
+    const hasIns = diffAdds > 0 || commitInsertions > 0;
+    if (!hasIns)
+        return true;
+    const showEmpty = NO_AUTHORSHIP_PLACEHOLDER.test((show ?? '').trim());
+    // Cursor/git-ai often updates `show` when authorship binds; avoid publishing while both are still "empty".
+    if (showEmpty && attributed === 0 && !hasBreakdown)
+        return false;
+    return true;
+}
+/**
+ * After `post-commit`, git-ai stats and `git-ai show` can lag behind the commit.
+ * Poll both until attribution is reflected (or timeout), then return the last stats snapshot.
+ */
+export async function waitForGitAiStats(cwd, ref, commitInsertions, opts) {
+    const maxWaitMs = opts?.maxWaitMs ?? 90_000;
+    const pollMs = opts?.pollMs ?? 500;
+    const deadline = Date.now() + maxWaitMs;
+    let last = null;
+    while (Date.now() < deadline) {
+        const [stats, show] = await Promise.all([getStats(cwd, ref), getShow(cwd, ref)]);
+        last = stats;
+        if (publishDataReady(stats, show, commitInsertions))
+            return stats;
+        await sleep(pollMs);
+    }
+    return last;
+}
+export async function getDiff(cwd, ref = 'HEAD') {
+    const r = await exec('git-ai', ['diff', ref, '--json'], { cwd, timeout: 15_000 });
+    if (r.exitCode !== 0)
+        return null;
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+export async function getShow(cwd, ref = 'HEAD') {
+    const r = await exec('git-ai', ['show', ref], { cwd, timeout: 15_000 });
+    return r.exitCode === 0 ? r.stdout.trim() : null;
+}
+export async function getPrompt(cwd, promptId, commitRef = 'HEAD') {
+    const r = await exec('git-ai', ['show-prompt', promptId, '--commit', commitRef], {
+        cwd,
+        timeout: 10_000,
+    });
+    if (r.exitCode !== 0)
+        return null;
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/git.d.ts

@@ -0,0 +1,21 @@
+export interface CommitInfo {
+    sha: string;
+    parentShas: string[];
+    subject: string;
+    body: string;
+    authorName: string;
+    authorEmail: string;
+    committerName: string;
+    committerEmail: string;
+    authoredAt: string;
+    committedAt: string;
+    branch: string;
+    additions: number;
+    deletions: number;
+    changedFiles: number;
+}
+export declare function getCommitInfo(cwd: string, ref?: string): Promise<CommitInfo>;
+export declare function getBranch(cwd: string): Promise<string>;
+export declare function getOriginUrl(cwd: string): Promise<string | null>;
+export declare function getRepoRoot(cwd: string): Promise<string>;
+export declare function getUserEmail(cwd: string): Promise<string>;

package/dist/lib/git.js

@@ -0,0 +1,67 @@
+import { exec, execOrThrow } from './exec.js';
+export async function getCommitInfo(cwd, ref = 'HEAD') {
+    const fmt = [
+        '%H', // sha
+        '%P', // parents (space-separated)
+        '%s', // subject
+        '%b', // body
+        '%an', // author name
+        '%ae', // author email
+        '%cn', // committer name
+        '%ce', // committer email
+        '%aI', // author date ISO
+        '%cI', // commit date ISO
+    ].join('%x00');
+    const log = await execOrThrow('git', ['log', '-1', `--format=${fmt}`, ref], { cwd });
+    const parts = log.stdout.trimEnd().split('\0');
+    const branch = await getBranch(cwd);
+    const stat = await execOrThrow('git', ['diff-tree', '--shortstat', ref], { cwd });
+    const { additions, deletions, changedFiles } = parseShortstat(stat.stdout);
+    return {
+        sha: parts[0] ?? '',
+        parentShas: (parts[1] ?? '').split(' ').filter(Boolean),
+        subject: parts[2] ?? '',
+        body: parts[3] ?? '',
+        authorName: parts[4] ?? '',
+        authorEmail: parts[5] ?? '',
+        committerName: parts[6] ?? '',
+        committerEmail: parts[7] ?? '',
+        authoredAt: parts[8] ?? '',
+        committedAt: parts[9] ?? '',
+        branch,
+        additions,
+        deletions,
+        changedFiles,
+    };
+}
+export async function getBranch(cwd) {
+    const r = await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
+    return r.exitCode === 0 ? r.stdout.trim() : 'unknown';
+}
+export async function getOriginUrl(cwd) {
+    const r = await exec('git', ['remote', 'get-url', 'origin'], { cwd });
+    return r.exitCode === 0 ? r.stdout.trim() : null;
+}
+export async function getRepoRoot(cwd) {
+    const r = await execOrThrow('git', ['rev-parse', '--show-toplevel'], { cwd });
+    return r.stdout.trim();
+}
+export async function getUserEmail(cwd) {
+    const r = await exec('git', ['config', 'user.email'], { cwd });
+    return r.exitCode === 0 ? r.stdout.trim() : 'unknown';
+}
+function parseShortstat(raw) {
+    let additions = 0;
+    let deletions = 0;
+    let changedFiles = 0;
+    const filesMatch = raw.match(/(\d+) files? changed/);
+    if (filesMatch?.[1])
+        changedFiles = Number.parseInt(filesMatch[1], 10);
+    const insertMatch = raw.match(/(\d+) insertions?\(\+\)/);
+    if (insertMatch?.[1])
+        additions = Number.parseInt(insertMatch[1], 10);
+    const delMatch = raw.match(/(\d+) deletions?\(-\)/);
+    if (delMatch?.[1])
+        deletions = Number.parseInt(delMatch[1], 10);
+    return { additions, deletions, changedFiles };
+}

package/dist/lib/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function promptSecret(message: string): Promise<string>;
+export declare function promptConfirm(message: string): Promise<boolean>;

package/dist/lib/prompt.js

@@ -0,0 +1,45 @@
+import * as readline from 'node:readline';
+export async function promptSecret(message) {
+    if (!process.stdin.isTTY) {
+        throw new Error('No TTY available for interactive token prompt. Set GENTRACE_API_KEY instead.');
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        process.stderr.write(message);
+        const prev = process.stdin.isRaw;
+        process.stdin.setRawMode?.(true);
+        let buf = '';
+        const onData = (ch) => {
+            const s = ch.toString();
+            if (s === '\n' || s === '\r') {
+                process.stdin.setRawMode?.(prev ?? false);
+                process.stdin.removeListener('data', onData);
+                process.stderr.write('\n');
+                rl.close();
+                resolve(buf);
+            }
+            else if (s === '\u0003') {
+                // ctrl-c
+                process.stderr.write('\n');
+                rl.close();
+                process.exit(130);
+            }
+            else if (s === '\u007f' || s === '\b') {
+                buf = buf.slice(0, -1);
+            }
+            else {
+                buf += s;
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+export async function promptConfirm(message) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}

package/dist/lib/skip.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Matches a repository identifier against a list of skip patterns.
+ * Patterns can be globs (simple * matching), exact URLs, or paths.
+ * Aligned with Git AI's exclude_repositories semantics.
+ */
+export declare function matchesSkipList(repoId: string, patterns: string[]): boolean;

package/dist/lib/skip.js

@@ -0,0 +1,19 @@
+/**
+ * Matches a repository identifier against a list of skip patterns.
+ * Patterns can be globs (simple * matching), exact URLs, or paths.
+ * Aligned with Git AI's exclude_repositories semantics.
+ */
+export function matchesSkipList(repoId, patterns) {
+    return patterns.some((p) => matchPattern(repoId, p));
+}
+function matchPattern(repoId, pattern) {
+    if (pattern === '*')
+        return true;
+    if (pattern === repoId)
+        return true;
+    if (pattern.includes('*')) {
+        const regex = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`);
+        return regex.test(repoId);
+    }
+    return false;
+}

package/dist/lib/telemetry-post.d.ts

@@ -0,0 +1,14 @@
+export interface TelemetryPostResult {
+    ok: boolean;
+    status: number;
+    responseText: string;
+}
+/**
+ * POST telemetry batch with exponential backoff when the server is unavailable or overloaded.
+ * Does not retry 401/403/409 (caller handles terminal auth / duplicate semantics).
+ */
+export declare function postTelemetryWithRetries(url: string, apiKey: string, bodyJson: string, opts?: {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    timeoutMs?: number;
+}): Promise<TelemetryPostResult>;

package/dist/lib/telemetry-post.js

@@ -0,0 +1,60 @@
+import { debugLog } from './debug.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableHttpStatus(status) {
+    return (status === 408 ||
+        status === 425 ||
+        status === 429 ||
+        status === 500 ||
+        status === 502 ||
+        status === 503 ||
+        status === 504);
+}
+/**
+ * POST telemetry batch with exponential backoff when the server is unavailable or overloaded.
+ * Does not retry 401/403/409 (caller handles terminal auth / duplicate semantics).
+ */
+export async function postTelemetryWithRetries(url, apiKey, bodyJson, opts) {
+    const maxAttempts = opts?.maxAttempts ?? 6;
+    const baseDelayMs = opts?.baseDelayMs ?? 1500;
+    const timeoutMs = opts?.timeoutMs ?? 30_000;
+    let last = { ok: false, status: 0, responseText: '' };
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': apiKey,
+                },
+                body: bodyJson,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const responseText = await res.text();
+            last = { ok: res.ok, status: res.status, responseText };
+            if (res.ok || res.status === 401 || res.status === 403 || res.status === 409) {
+                return last;
+            }
+            if (attempt < maxAttempts && isRetryableHttpStatus(res.status)) {
+                const wait = baseDelayMs * 2 ** (attempt - 1);
+                debugLog(`telemetry HTTP ${res.status}, retry in ${wait}ms (${attempt}/${maxAttempts})`);
+                await sleep(wait);
+                continue;
+            }
+            return last;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            last = { ok: false, status: 0, responseText: message };
+            if (attempt < maxAttempts) {
+                const wait = baseDelayMs * 2 ** (attempt - 1);
+                debugLog(`telemetry fetch error, retry in ${wait}ms (${attempt}/${maxAttempts})`, err);
+                await sleep(wait);
+                continue;
+            }
+            return last;
+        }
+    }
+    return last;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@qodly/gentrace",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "gentrace": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "install:global": "bash scripts/install-global.sh",
+    "version:patch": "npm version patch --no-workspaces",
+    "version:minor": "npm version minor --no-workspaces",
+    "version:major": "npm version major --no-workspaces",
+    "publish:npm": "npm publish --no-workspaces",
+    "install:npm": "npm install --workspaces=false",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "bun src/cli.ts",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "bun test --pass-with-no-tests"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@gentrace/types": "file:../../packages/shared-types",
+    "typescript": "^6.0.3",
+    "@types/bun": "latest",
+    "@types/node": "^25.7.0"
+  }
+}