@qodly/gentrace 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# Gentrace CLI (`gentrace`)
+
+Command-line bridge between **[git-ai](https://github.com/git-ai/git-ai)** and the **Gentrace** API: after each commit it can send **`commit_attribution`** telemetry (AI vs human line stats, diff context, and optional prompts) to `POST /v1/telemetry`.
+
+Package name on npm: **`@qodly/gentrace`** · binary: **`gentrace`**
+
+---
+
+## Prerequisites
+
+| Requirement | Purpose |
+|-------------|---------|
+| **Git** | Repository detection, hooks, diff, commit metadata. |
+| **[git-ai](https://github.com/git-ai/git-ai)** | Records attribution for commits; the CLI reads git-ai output to build telemetry. |
+| **[Bun](https://bun.sh)** | The published `gentrace` entrypoint (`dist/cli.js`) uses `#!/usr/bin/env bun` — install Bun and ensure it is on your `PATH`. |
+| **Gentrace account** | Sign in to your Gentrace dashboard, create an **access token** with permission to ingest telemetry (see below). |
+
+Optional:
+
+- **curl** / **bash** — used by `gentrace install-git-ai` for the official git-ai installer on macOS/Linux.
+
+---
+
+## Install
+
+### From npm (recommended)
+
+```bash
+npm install -g @qodly/gentrace
+```
+
+Verify:
+
+```bash
+gentrace --version
+```
+
+### One-off run with npx
+
+```bash
+npx @qodly/gentrace@latest doctor
+```
+
+### From this monorepo (contributors)
+
+From the repository root (requires [Bun](https://bun.sh)):
+
+```bash
+bun run --filter @qodly/gentrace install:global
+```
+
+Or from `apps/cli`:
+
+```bash
+cd apps/cli && bun run install:global
+```
+
+That script builds the CLI and links the `gentrace` command globally. See `scripts/install-global.sh` for flags (e.g. `--no-build`).
+
+---
+
+## Getting started
+
+### 1. Install git-ai
+
+If `git-ai` is not installed:
+
+```bash
+gentrace install-git-ai
+```
+
+This runs the installer from [usegitai.com](https://usegitai.com). On Windows (native), the command prints a PowerShell one-liner; on WSL/macOS/Linux it offers the `curl … \| bash` flow. After installation, reload your shell or add `~/.git-ai/bin` to `PATH` if the binary is not found.
+
+Confirm:
+
+```bash
+gentrace doctor
+```
+
+`doctor` checks `git`, `git-ai`, API configuration, and API reachability.
+
+### 2. Create an API token in the dashboard
+
+1. Open your Gentrace web app (for example `https://gentrace.4d-ps.com`) and sign in.
+2. Go to **Settings** (personal access tokens), e.g. `https://gentrace.4d-ps.com/settings`.
+3. Create **New access token**.
+4. Grant at least **`telemetry:ingest`** (or **`*`**) so `gentrace publish` can send batches. Tokens used only for ingest often include `telemetry:ingest`; `gentrace doctor` also calls `GET /v1/auth/permissions`, which requires sufficient IAM on the token (see doctor output if something fails).
+
+Copy the token **once** — it may not be shown again.
+
+### 3. Configure the API key (and optional API URL)
+
+**Interactive** (saved to `~/.config/gentrace/config.json`):
+
+```bash
+gentrace doctor
+```
+
+If no key is set, `doctor` can prompt for it when a TTY is available.
+
+**Explicit**:
+
+```bash
+gentrace config set apiKey 'YOUR_TOKEN_HERE'
+```
+
+Default API base URL is `https://gentrace.4d-ps.com/api` (paths such as `/v1/telemetry` are appended to this base). Override if needed:
+
+```bash
+gentrace config set apiUrl 'https://your-host.example.com/api'
+```
+
+Or use environment variables (highest precedence for URL/key):
+
+```bash
+export GENTRACE_API_KEY='YOUR_TOKEN_HERE'
+export GENTRACE_API_URL='https://your-host.example.com/api'
+```
+
+### 4. Verify the setup
+
+```bash
+gentrace doctor
+```
+
+You should see checks for git, git-ai, API key, HTTP health, and token IAMs for telemetry ingest.
+
+### 5. Install the post-commit hook (per repository)
+
+In each Git repo where you want automatic publishes after every commit:
+
+```bash
+cd /path/to/your/repo
+gentrace hooks install
+```
+
+Optional second argument: path to the repo root:
+
+```bash
+gentrace hooks install /path/to/your/repo
+```
+
+The hook runs **`gentrace publish --daemon`** in the background (`nohup`) so commits are not blocked. Logs go to `.git/gentrace-publish.log`.
+
+Ensure **`gentrace`** is on `PATH` when Git runs hooks (same as in your interactive shell), or set **`GENTRACE_BIN`** to the full path of the binary in the environment used by GUI Git clients / CI if needed.
+
+### 6. Manual publish (optional test)
+
+From a repo with git-ai data for `HEAD`:
+
+```bash
+gentrace publish
+```
+
+Optional working directory:
+
+```bash
+gentrace publish /path/to/repo
+```
+
+---
+
+## Command reference
+
+Global notes:
+
+- **`gentrace --help`** / **`-h`** — short usage summary.
+- **`gentrace --version`** / **`-V`** — CLI version string.
+- **Verbose logging** — place **`--verbose`**, **`--debug`**, or **`-v`** before the subcommand (or on supported commands such as `publish` / `doctor`) to log HTTP details to stderr. Same effect: **`GENTRACE_DEBUG=1`** (or `true`).
+
+---
+
+### `gentrace publish`
+
+Collects Git AI attribution and git metadata for **HEAD** in a repository, builds a telemetry batch, and **POST**s it to **`{apiUrl}/v1/telemetry`**.
+
+**Usage**
+
+```text
+gentrace publish [--verbose|--debug|-v] [--daemon|--background] [cwd]
+```
+
+| Argument / flag | Description |
+|-----------------|-------------|
+| **`cwd`** | Optional path to the repository root (defaults to current working directory). |
+| **`--daemon`** / **`--background`** | After a delay, run collection in a style suited to hooks: waits **`GENTRACE_PUBLISH_DELAY_MS`** ms if set, otherwise **2500** ms, so git-ai can finish writing stats. Then collects and sends. |
+| **Verbose flags** | Extra stderr logs (URL, redacted headers, body preview, response). |
+
+**Behavior highlights**
+
+- Skips the run if the repository id (origin URL, or path fallback) matches **`skipRepositories`** (see `gentrace skip`).
+- Requires **git-ai** on PATH; exits with a hint to run **`gentrace install-git-ai`** if missing.
+- Resolves API key from **`GENTRACE_API_KEY`** or config; may prompt once in a TTY.
+- **200**: prints accepted count when present in JSON body.
+- **409**: treated as already recorded (“Commit … already recorded”).
+- **401** / **403**: auth error; suggests checking the token and **`telemetry:ingest`**.
+
+---
+
+### `gentrace doctor`
+
+Validates local tools and API connectivity.
+
+**Usage**
+
+```text
+gentrace doctor [--verbose|--debug|-v]
+```
+
+**Checks (in order)**
+
+1. **`git`** on PATH.  
+2. **`git-ai`** on PATH.  
+3. **API key** — from env or config; may prompt and save in a TTY.  
+4. **`GET {apiUrl}/health`** — unauthenticated liveness.  
+5. **`GET {apiUrl}/v1/auth/permissions`** with **`X-API-Key`** — confirms token works and IAMs include **`telemetry:ingest`** or **`*`** for publish.
+
+Exits **`0`** if all checks pass, **`1`** otherwise.
+
+---
+
+### `gentrace install-git-ai`
+
+If git-ai is already installed, prints the version and exits.
+
+Otherwise (on Unix/WSL) asks for confirmation, then runs:
+
+`curl -sSL https://usegitai.com/install.sh | bash`
+
+On Windows (non-WSL), prints the recommended PowerShell install command instead.
+
+---
+
+### `gentrace hooks install` / `gentrace hooks uninstall`
+
+Manage a **post-commit** shell hook under **`.git/hooks/post-commit`**.
+
+**Usage**
+
+```text
+gentrace hooks install [cwd]
+gentrace hooks uninstall [cwd]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| **`install`** | Ensures `.git/hooks` exists, then appends or creates a block marked `# gentrace-cli post-commit hook` that runs **`nohup gentrace publish --daemon`** (with **`GENTRACE_BIN`** defaulting to `gentrace`). If an older gentrace hook exists, it may be replaced with the async version. May prompt for API key once. |
+| **`uninstall`** | Removes only the gentrace-marked section; deletes the file if nothing else remains (except a bare `#!/bin/sh`). |
+
+**`cwd`** — optional path to the repo root (default: current directory).
+
+---
+
+### `gentrace config`
+
+Read or write **`~/.config/gentrace/config.json`**.
+
+**Usage**
+
+```text
+gentrace config                       # print full JSON (apiKey masked)
+gentrace config get [key]             # get one key or all if omitted in some forms
+gentrace config set <key> <value>     # set scalar keys (see below)
+gentrace config unset <key>           # reset key to default
+gentrace config <key>                 # same as: config get <key>
+```
+
+**Keys**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| **`apiUrl`** | string | API base URL (default includes `/api` path; see source `DEFAULTS`). |
+| **`apiKey`** | string | Secret token (`get` shows a masked value). |
+| **`includePrompts`** | boolean | Set with `gentrace config set includePrompts true` or `false` — when true, publish may attach prompt payloads derived from the authorship log (heavier / more sensitive). |
+| **`skipRepositories`** | string[] | Prefer managing via **`gentrace skip`**; patterns match repository id (origin URL or path), with simple `*` glob support. |
+
+---
+
+### `gentrace skip`
+
+Manage the **skip list** so **`gentrace publish`** (and the hook) no-op for matching repositories.
+
+**Usage**
+
+```text
+gentrace skip add <pattern>
+gentrace skip remove <pattern>
+gentrace skip list
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| **`add`** | Append a pattern if not already present. |
+| **`remove`** | Remove an exact pattern entry. |
+| **`list`** | Print all patterns (or a message if empty). |
+
+**Matching** — `*` matches any repository; otherwise exact match, or glob if the pattern contains `*`.
+
+---
+
+## Configuration file
+
+- **Path:** `~/.config/gentrace/config.json` (or **`$XDG_CONFIG_HOME/gentrace/config.json`** when set).  
+- **Permissions:** written with mode **0600**.  
+- **Precedence:** **`GENTRACE_API_URL`** / **`GENTRACE_API_KEY`** override saved values when set.
+
+---
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| **`GENTRACE_API_KEY`** | API token (overrides config file). |
+| **`GENTRACE_API_URL`** | API base URL (overrides config file). |
+| **`GENTRACE_DEBUG`** | Set to `1` or `true` for verbose stderr logs. |
+| **`GENTRACE_PUBLISH_DELAY_MS`** | Milliseconds to wait before collecting when using **`--daemon`** (default **2500** when daemon; **`0`** when not daemon unless this env is set). |
+| **`GENTRACE_BIN`** | Used by the post-commit hook: full path to **`gentrace`** if it is not on the default `PATH` for non-interactive Git. |
+
+---
+
+## Related documentation
+
+- Monorepo CLI overview: [`../../docs/cli.md`](../../docs/cli.md)  
+- API / webhooks / IAM concepts: repository root **`README.md`** and **`ARCHITECTURE.md`**

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env bun
+import { configGet, configSet, configUnset } from './commands/config.js';
+import { doctor } from './commands/doctor.js';
+import { hooksInstall, hooksUninstall } from './commands/hooks.js';
+import { installGitAi } from './commands/install-git-ai.js';
+import { publish } from './commands/publish.js';
+import { skipAdd, skipList, skipRemove } from './commands/skip.js';
+import { enableDebug, VERBOSE_FLAGS } from './lib/debug.js';
+const VERSION = '2.0.0';
+const HELP = `\
+gentrace - Git AI → Gentrace telemetry bridge
+
+Usage:
+  gentrace <command> [options]
+
+Commands:
+  publish              Collect Git AI data for HEAD and send to Gentrace API
+                         Use --daemon from hooks: non-blocking + delay before collect
+  doctor               Check git, git-ai, API key, and API reachability
+  install-git-ai       Install the git-ai CLI if not already present
+
+  hooks install        Install post-commit hook in current repo
+  hooks uninstall      Remove post-commit hook from current repo
+
+  config               Show all configuration
+  config get <key>     Show a config value
+  config set <key> <v> Set a config value
+  config unset <key>   Reset a config value to default
+
+  skip add <pattern>   Add repo to skip list
+  skip remove <pat>    Remove repo from skip list
+  skip list            List skipped repos
+
+  --version, -V        Print version
+  --help, -h           Print this help
+
+  Place --verbose, --debug, or -v before a command or on publish/doctor for HTTP
+  and payload traces on stderr. Same effect: GENTRACE_DEBUG=1.
+
+Environment:
+  GENTRACE_API_KEY     API key (overrides config file)
+  GENTRACE_API_URL     API base URL (overrides config file)
+  GENTRACE_DEBUG       Set to 1/true for verbose stderr logs
+  GENTRACE_PUBLISH_DELAY_MS  Milliseconds to wait before reading git-ai (default 2500 with --daemon)
+  GENTRACE_BIN         Used by post-commit hook; path to gentrace binary
+
+Config file: ~/.config/gentrace/config.json
+`;
+async function main() {
+    let args = process.argv.slice(2);
+    while (args[0] && VERBOSE_FLAGS.has(args[0])) {
+        enableDebug();
+        args = args.slice(1);
+    }
+    const cmd = args[0];
+    if (!cmd || cmd === '--help' || cmd === '-h') {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === '--version' || cmd === '-V') {
+        console.log(`gentrace ${VERSION}`);
+        return;
+    }
+    switch (cmd) {
+        case 'publish':
+            await publish(args.slice(1));
+            break;
+        case 'doctor':
+            await doctor(args.slice(1));
+            break;
+        case 'install-git-ai':
+            await installGitAi();
+            break;
+        case 'hooks': {
+            const sub = args[1];
+            if (sub === 'install') {
+                await hooksInstall(args[2]);
+            }
+            else if (sub === 'uninstall') {
+                await hooksUninstall(args[2]);
+            }
+            else {
+                console.error('Usage: gentrace hooks install|uninstall');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'config': {
+            const sub = args[1];
+            if (!sub) {
+                configGet();
+            }
+            else if (sub === 'get') {
+                configGet(args[2]);
+            }
+            else if (sub === 'set') {
+                if (!args[2] || !args[3]) {
+                    console.error('Usage: gentrace config set <key> <value>');
+                    process.exit(1);
+                }
+                configSet(args[2], args[3]);
+            }
+            else if (sub === 'unset') {
+                if (!args[2]) {
+                    console.error('Usage: gentrace config unset <key>');
+                    process.exit(1);
+                }
+                configUnset(args[2]);
+            }
+            else {
+                // Treat as `config get <key>`
+                configGet(sub);
+            }
+            break;
+        }
+        case 'skip': {
+            const sub = args[1];
+            if (sub === 'add') {
+                if (!args[2]) {
+                    console.error('Usage: gentrace skip add <pattern>');
+                    process.exit(1);
+                }
+                skipAdd(args[2]);
+            }
+            else if (sub === 'remove') {
+                if (!args[2]) {
+                    console.error('Usage: gentrace skip remove <pattern>');
+                    process.exit(1);
+                }
+                skipRemove(args[2]);
+            }
+            else if (sub === 'list') {
+                skipList();
+            }
+            else {
+                console.error('Usage: gentrace skip add|remove|list');
+                process.exit(1);
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${cmd}\nRun 'gentrace --help' for usage.`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/commands/config.d.ts

@@ -0,0 +1,3 @@
+export declare function configGet(key?: string): void;
+export declare function configSet(key: string, value: string): void;
+export declare function configUnset(key: string): void;

package/dist/commands/config.js

@@ -0,0 +1,69 @@
+import { loadConfig, saveConfig } from '../lib/config.js';
+const VALID_KEYS = [
+    'apiUrl',
+    'apiKey',
+    'includePrompts',
+    'skipRepositories',
+];
+export function configGet(key) {
+    const cfg = loadConfig();
+    if (!key) {
+        const display = { ...cfg, apiKey: cfg.apiKey ? maskKey(cfg.apiKey) : '(not set)' };
+        console.log(JSON.stringify(display, null, 2));
+        return;
+    }
+    if (!isValidKey(key)) {
+        console.error(`Unknown config key: ${key}`);
+        console.error(`Valid keys: ${VALID_KEYS.join(', ')}`);
+        process.exit(1);
+    }
+    const val = cfg[key];
+    if (key === 'apiKey') {
+        console.log(val ? maskKey(val) : '(not set)');
+    }
+    else {
+        console.log(typeof val === 'object' ? JSON.stringify(val, null, 2) : String(val));
+    }
+}
+export function configSet(key, value) {
+    if (!isValidKey(key)) {
+        console.error(`Unknown config key: ${key}`);
+        console.error(`Valid keys: ${VALID_KEYS.join(', ')}`);
+        process.exit(1);
+    }
+    const patch = {};
+    if (key === 'includePrompts') {
+        patch.includePrompts = value === 'true';
+    }
+    else if (key === 'skipRepositories') {
+        const current = loadConfig();
+        patch.skipRepositories = [...new Set([...current.skipRepositories, value])];
+    }
+    else {
+        patch[key] = value;
+    }
+    saveConfig(patch);
+    console.log(`Set ${key}`);
+}
+export function configUnset(key) {
+    if (!isValidKey(key)) {
+        console.error(`Unknown config key: ${key}`);
+        process.exit(1);
+    }
+    const defaults = {
+        apiUrl: 'https://gentrace.4d-ps.com/api',
+        apiKey: '',
+        includePrompts: false,
+        skipRepositories: [],
+    };
+    saveConfig({ [key]: defaults[key] });
+    console.log(`Unset ${key} (reverted to default)`);
+}
+function isValidKey(key) {
+    return VALID_KEYS.includes(key);
+}
+function maskKey(key) {
+    if (key.length <= 8)
+        return '****';
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctor(argv?: string[]): Promise<void>;