pivotdude-git-ai 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.1] - 2026-07-01
+
+### Changed
+
+- Publish as unscoped `pivotdude-git-ai` on npm (scoped `@pivotdude/git-ai` was private and not installable).
+
+## [1.0.0] - 2026-07-01
+
+### Added
+
+- Initial public release extracted from the OpenTrade monorepo.
+- AI-assisted git workflows: commit-push, branch-commit-pr, create-pr, update-pr.
+- Project config via `.git-ai/` directory.
+- OpenAI-compatible, Cursor SDK, and manual AI providers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pivotdude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# git-ai
+
+AI-assisted git workflows: commit messages, branches, pull requests, and optional pre-commit fixes.
+
+Requires [Bun](https://bun.sh) >= 1.3 and `git` / `gh` on `PATH` for the full workflow.
+
+## Install
+
+```bash
+npm i -g pivotdude-git-ai
+# or
+bun add -g pivotdude-git-ai
+```
+
+Run from any directory inside a git repository:
+
+```bash
+git-ai
+git-ai --mode commit-push
+git-ai --provider manual
+```
+
+Monorepos can wire package scripts, e.g. `"git:ai": "git-ai"`.
+
+## Project config (`.git-ai/`)
+
+Optional files at the **git repository root**:
+
+| Path | Purpose |
+|------|---------|
+| `.git-ai/config.json` | `baseBranch`, `stagedFix`, optional `conventions` / `prTemplate` paths ([JSON Schema](config.schema.json)) |
+| `.git-ai/diff-ignore` | `.gitignore`-style patterns omitted from AI diffs (merged with built-in lockfile defaults) |
+| `.git-ai/prompts/*.md` | Per-mode prompt overrides (`commit-push.md`, `create-pr.md`, …) |
+| `.git-ai/conventions.md` | Commit/branch conventions when `conventions` is not set in `config.json` |
+
+See `project-config.example/` for a starter layout.
+
+Legacy `.git-ai.json` at the repo root is still read if `config.json` is missing.
+
+Point `$schema` in `config.json` at the published schema URL for editor autocomplete:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/pivotdude/git-ai/main/config.schema.json"
+}
+```
+
+## Dry run
+
+Print the assembled AI prompt without calling an API or running git actions:
+
+```bash
+git-ai --dry-run --mode commit-push
+git-ai -n --mode create-pr
+```
+
+Git state is still read (staged diff, branch log, etc.) to build the prompt.
+
+## `stagedFix` and shell commands
+
+`stagedFix` in `config.json` runs **arbitrary shell commands** from the repository root before commit (for example `bun --filter web fix`).
+
+- Only add commands you trust, in repositories you control.
+- Anyone who can change `.git-ai/config.json` can run shell code on your machine when you approve a git-ai commit.
+- Commands are executed with `sh -c`; failures are warned but do not always stop the workflow.
+
+Treat `.git-ai/` like other sensitive local tooling config (similar to custom git hooks).
+
+## AI providers
+
+| Provider | Env vars |
+|----------|----------|
+| OpenAI-compatible | `OPENAI_BASE_URL`, `OPENAI_API_KEY`, optional `OPENAI_MODEL` |
+| Cursor SDK | `CURSOR_API_KEY`, optional `CURSOR_MODEL` |
+| Manual | Copies prompt to clipboard / `$EDITOR`; no API key |
+
+Before applying, you can **edit** individual fields (branch, commit message, PR title, description) in `$EDITOR`.
+
+Uses `$VISUAL` or `$EDITOR` (default `nano`) for manual provider responses and pre-apply edits.
+
+When the API returns token usage (OpenAI-compatible providers), git-ai prints a one-line `[tokens]` summary with in/out/total counts. Cost is shown only when included in the response (e.g. some OpenRouter payloads).
+
+## Development
+
+```bash
+bun install
+bun run check      # typecheck
+bun run lint:check
+bun test           # unit tests
+bun run build
+```
+
+Suggested validation before opening a PR or publishing:
+
+```bash
+bun run validate:local-release
+```
+
+## npm release flow
+
+1. Bump `package.json.version`.
+2. Commit and push to GitHub.
+3. Create and push tag `v<version>` (for example `v1.0.1`).
+4. Publish a GitHub Release from that tag.
+5. GitHub Actions publishes the package to npm with the `latest` tag (`NPM_TOKEN` secret required).
+
+## License
+
+MIT

package/bin/git-ai.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../dist/index.js";

package/config.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/pivotdude/git-ai/main/config.schema.json",
+  "title": "git-ai project config",
+  "description": "Optional settings in .git-ai/config.json at the git repository root.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema URL or path for editor validation."
+    },
+    "baseBranch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Default base branch for create-pr / update-pr diff and PR target.",
+      "default": "main"
+    },
+    "diffIgnore": {
+      "type": "array",
+      "description": "Extra .gitignore-style patterns omitted from AI diffs. Merged with .git-ai/diff-ignore and built-in lockfile defaults.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "conventions": {
+      "type": ["string", "null"],
+      "description": "Repo-relative path to commit/branch conventions markdown. Null uses .git-ai/conventions.md or the bundled default."
+    },
+    "prTemplate": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repo-relative path to the pull request template markdown.",
+      "default": ".github/PULL_REQUEST_TEMPLATE.md"
+    },
+    "stagedFix": {
+      "type": "object",
+      "description": "Optional lint/format commands run before commit. Executes arbitrary shell from the repository root.",
+      "additionalProperties": false,
+      "properties": {
+        "rules": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/stagedFixRule" },
+          "default": []
+        },
+        "root": {
+          "oneOf": [{ "$ref": "#/$defs/stagedFixRule" }, { "type": "null" }],
+          "default": null
+        }
+      },
+      "default": { "rules": [], "root": null }
+    }
+  },
+  "$defs": {
+    "stagedFixRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["paths", "command"],
+      "properties": {
+        "paths": {
+          "type": "array",
+          "minItems": 1,
+          "description": ".gitignore-style path patterns. Command runs when any staged file matches.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Shell command executed from the repository root (sh -c)."
+        }
+      }
+    }
+  }
+}

package/dist/cursor-sdk-runner.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+
+import { Agent, CursorAgentError } from '@cursor/sdk';
+
+const apiKey = process.env.CURSOR_API_KEY;
+const model = process.env.CURSOR_MODEL ?? 'composer-2.5';
+const promptPath = process.argv[2];
+
+if (!apiKey) {
+  console.error('CURSOR_API_KEY is required');
+  process.exit(1);
+}
+
+if (!promptPath) {
+  console.error('Usage: cursor-sdk-runner.mjs <prompt-file>');
+  process.exit(1);
+}
+
+const prompt = await readFile(promptPath, 'utf8');
+
+try {
+  const result = await Agent.prompt(prompt, {
+    apiKey,
+    model: { id: model },
+    local: { cwd: process.cwd(), settingSources: [] },
+  });
+
+  if (result.status === 'error') {
+    console.error(`Cursor agent run failed: ${result.id}`);
+    process.exit(2);
+  }
+
+  const content = result.result?.trim();
+  if (!content) {
+    console.error('Empty response from Cursor agent');
+    process.exit(2);
+  }
+
+  process.stdout.write(content);
+} catch (error) {
+  if (error instanceof CursorAgentError) {
+    console.error(`Cursor SDK startup failed: ${error.message}`);
+    process.exit(1);
+  }
+
+  throw error;
+}