opencode-git-trailers 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Lannutti
+
+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,161 @@
+# opencode-git-trailers
+
+OpenCode plugin that automatically adds git trailers to commits made through OpenCode.
+
+## Problem
+
+Some projects require commits created with AI assistance to include metadata denoting this fact. Git trailers provide a standardized way to add such metadata to commit messages. This plugin ensures that trailers are deterministically added to all commits made through OpenCode.
+
+## What It Does
+
+This plugin intercepts `git commit` commands invoked by OpenCode and automatically appends configured trailers to the commit message. Trailers are added to the end of the commit message following the [git trailer format](https://git-scm.com/docs/git-interpret-trailers).
+
+## Installation
+
+```bash
+npm install opencode-git-trailers
+```
+
+## Usage
+
+### Basic Setup
+
+Add the plugin to your OpenCode configuration:
+
+```json
+{
+  "plugins": ["opencode-git-trailers"]
+}
+```
+
+### Configuration
+
+Configure trailers using git config with the `opencode.git-trailers` prefix.
+
+#### Global Configuration
+
+Configure trailers globally to apply to all repositories:
+
+```bash
+# Add the model used for the commit
+git config --global opencode.git-trailers.model '{{model}}'
+
+# Add yourself as a co-author with the AI
+git config --global opencode.git-trailers.co-authored-by 'AI Assistant <ai@opencode.ai>'
+
+# Add a signed-off-by trailer
+git config --global opencode.git-trailers.signed-off-by '{{user.name}} <{{user.email}}>'
+```
+
+#### Per-Repository Configuration
+
+Configure trailers for a specific repository by running commands within the repository directory:
+
+```bash
+# Navigate to your repository
+cd /path/to/your/repo
+
+# Add the model used for the commit (repository-specific)
+git config opencode.git-trailers.model '{{model}}'
+
+# Add a signed-off-by trailer (repository-specific)
+git config opencode.git-trailers.signed-off-by '{{user.name}} <{{user.email}}>'
+```
+
+Per-repository configuration overrides global configuration for the same trailer key.
+
+#### Result
+
+These configuration options result in the following trailers being added to commits:
+
+```
+Model: claude-sonnet-4-5@20250929
+Co-authored-by: AI Assistant <ai@opencode.ai>
+Signed-off-by: John Doe <john@example.com>
+```
+
+### Variable Interpolation
+
+Trailers support variable interpolation to include contextual information such as the model used:
+
+```bash
+# Configure a trailer with model interpolation
+git config opencode.git-trailers.model '{{model}}'
+
+# Use git user information
+git config opencode.git-trailers.signed-off-by '{{user.name}} <{{user.email}}>'
+```
+
+#### Available Variables
+
+- `{{model}}` - The model identifier used for the commit
+- `{{provider}}` - The provider name (e.g., "anthropic", "openai")
+- `{{timestamp}}` - ISO 8601 timestamp of the commit
+- `{{session}}` - OpenCode session ID
+- `{{user.name}}` - Git user name from git config
+- `{{user.email}}` - Git user email from git config
+
+### Example Commit Message
+
+Before this plugin:
+
+```
+Add user authentication
+
+This commit implements JWT-based authentication
+for the API endpoints.
+```
+
+After this plugin (with configured trailers):
+
+```
+Add user authentication
+
+This commit implements JWT-based authentication
+for the API endpoints.
+
+Model: claude-sonnet-4-5@20250929
+Co-authored-by: AI Assistant <ai@opencode.ai>
+Signed-off-by: John Doe <john@example.com>
+```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) 1.x or later
+
+### Setup
+
+```bash
+bun install
+```
+
+### Build
+
+```bash
+bun run build
+```
+
+### Test
+
+```bash
+# Run tests once
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+
+# Run tests with coverage
+bun run test:coverage
+```
+
+### Lint
+
+```bash
+bun run lint
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { ShellAPI } from "./types.js";
+/**
+ * Reads git trailer configuration from git config.
+ * Looks for config keys starting with "opencode.git-trailers."
+ * @param $shell - OpenCode's shell API
+ * @param cwd - Current working directory
+ * @returns Record of trailer configuration key-value pairs
+ */
+export declare function readGitTrailers($shell: ShellAPI, cwd: string): Promise<Record<string, string>>;

package/dist/config.js

@@ -0,0 +1,30 @@
+const TRAILER_PREFIX = "opencode.git-trailers.";
+/**
+ * Reads git trailer configuration from git config.
+ * Looks for config keys starting with "opencode.git-trailers."
+ * @param $shell - OpenCode's shell API
+ * @param cwd - Current working directory
+ * @returns Record of trailer configuration key-value pairs
+ */
+export async function readGitTrailers($shell, cwd) {
+    const configOutput = await $shell `git config --get-regexp '^opencode\.git-trailers\.'`
+        .cwd(cwd)
+        .nothrow()
+        .quiet()
+        .text();
+    if (!configOutput.trim()) {
+        return {};
+    }
+    const trailers = {};
+    const lines = configOutput.trim().split("\n");
+    for (const line of lines) {
+        const spaceIndex = line.indexOf(" ");
+        if (spaceIndex === -1)
+            continue;
+        const fullKey = line.substring(0, spaceIndex);
+        const value = line.substring(spaceIndex + 1);
+        const trailerName = fullKey.substring(TRAILER_PREFIX.length);
+        trailers[trailerName] = value;
+    }
+    return trailers;
+}

package/dist/git-commit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks if a command is a git commit command.
+ * Handles both standalone and chained commands (using && or ;).
+ * @param command - The command string to check
+ * @returns True if the command contains "git commit"
+ */
+export declare function isGitCommitCommand(command: string): boolean;
+/**
+ * Extracts the commit message from a git commit command.
+ * Supports double-quoted, single-quoted, and unquoted message formats.
+ * @param command - The git commit command
+ * @returns The extracted commit message, or null if not found
+ */
+export declare function extractCommitMessage(command: string): string | null;

package/dist/git-commit.js

@@ -0,0 +1,44 @@
+/**
+ * Checks if a command is a git commit command.
+ * Handles both standalone and chained commands (using && or ;).
+ * @param command - The command string to check
+ * @returns True if the command contains "git commit"
+ */
+export function isGitCommitCommand(command) {
+    const trimmed = command.trim();
+    // Check if it starts with "git commit"
+    if (trimmed.startsWith("git commit")) {
+        return true;
+    }
+    // Check for git commit in chained commands
+    // Match: && git commit or ; git commit (with word boundaries)
+    return /[;&]\s*git\s+commit\b/.test(command);
+}
+/**
+ * Extracts the commit message from a git commit command.
+ * Supports double-quoted, single-quoted, and unquoted message formats.
+ * @param command - The git commit command
+ * @returns The extracted commit message, or null if not found
+ */
+export function extractCommitMessage(command) {
+    if (!isGitCommitCommand(command)) {
+        return null;
+    }
+    // Match double-quoted strings, handling escaped quotes (\")
+    const doubleQuoteMatch = command.match(/-m\s+"((?:\\"|[^"])*)"/);
+    if (doubleQuoteMatch) {
+        // Unescape the matched content
+        return doubleQuoteMatch[1]
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, '\\');
+    }
+    const singleQuoteMatch = command.match(/-m\s+'([^']*)'/);
+    if (singleQuoteMatch) {
+        return singleQuoteMatch[1];
+    }
+    const unquotedMatch = command.match(/-m\s+(\S+)/);
+    if (unquotedMatch) {
+        return unquotedMatch[1];
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,63 @@
+import { readGitTrailers } from "./config.js";
+import { isGitCommitCommand } from "./git-commit.js";
+import { modifyGitCommitCommand } from "./modify-command.js";
+import { buildTrailers } from "./trailers.js";
+import { getUserVariables, buildContextVariables } from "./variables.js";
+const plugin = async (input) => {
+    // Store model/provider in closure to access across hooks
+    let currentModel;
+    let currentProvider;
+    return {
+        "chat.params": async (hookInput) => {
+            // Capture model and provider from chat parameters
+            try {
+                if (hookInput.model?.id) {
+                    currentModel = hookInput.model.id;
+                }
+                if (hookInput.provider?.info?.name) {
+                    currentProvider = hookInput.provider.info.name;
+                }
+            }
+            catch {
+                // Silently ignore errors in capturing model/provider
+            }
+        },
+        "tool.execute.before": async (hookInput, output) => {
+            try {
+                // Only process bash tool
+                if (hookInput.tool !== "bash") {
+                    return;
+                }
+                const command = output.args?.command;
+                if (!command || !isGitCommitCommand(command)) {
+                    return;
+                }
+                // Read git trailer configuration
+                const workdir = output.args?.workdir;
+                const cwd = (typeof workdir === 'string' ? workdir : undefined) || input.directory;
+                const trailerConfig = await readGitTrailers(input.$, cwd);
+                if (Object.keys(trailerConfig).length === 0) {
+                    return;
+                }
+                // Collect all variables
+                const userVars = await getUserVariables(input.$, cwd);
+                const contextVars = buildContextVariables({
+                    session: hookInput.sessionID,
+                    model: currentModel,
+                    provider: currentProvider,
+                });
+                const allVariables = { ...userVars, ...contextVars };
+                // Build and apply trailers
+                const trailers = buildTrailers(trailerConfig, allVariables);
+                const modifiedCommand = modifyGitCommitCommand(command, trailers);
+                output.args.command = modifiedCommand;
+            }
+            catch (error) {
+                // Gracefully handle errors - don't break the commit
+                // Log error for debugging but allow commit to proceed unchanged
+                console.error("opencode-git-trailers: Error processing trailers:", error);
+            }
+        },
+    };
+};
+export default plugin;

package/dist/interpolate.d.ts

@@ -0,0 +1,10 @@
+import type { Variables } from "./types.js";
+/**
+ * Interpolates variables into a template string.
+ * Variables are referenced using {{variableName}} or {{nested.path}} syntax.
+ * Undefined variables are left as-is in the template.
+ * @param template - Template string with variable placeholders
+ * @param variables - Record of variable values
+ * @returns Template with variables interpolated
+ */
+export declare function interpolateVariables(template: string, variables: Variables): string;

package/dist/interpolate.js

@@ -0,0 +1,13 @@
+/**
+ * Interpolates variables into a template string.
+ * Variables are referenced using {{variableName}} or {{nested.path}} syntax.
+ * Undefined variables are left as-is in the template.
+ * @param template - Template string with variable placeholders
+ * @param variables - Record of variable values
+ * @returns Template with variables interpolated
+ */
+export function interpolateVariables(template, variables) {
+    return template.replace(/\{\{(\w+(?:\.\w+)*)\}\}/g, (_, key) => {
+        return variables[key] ?? `{{${key}}}`;
+    });
+}

package/dist/modify-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Escapes a string for use within $'...' ANSI-C quoting.
+ * @param str - String to escape
+ * @returns Escaped string safe for $'...' context
+ */
+export declare function escapeForAnsiCQuotes(str: string): string;
+/**
+ * Modifies a git commit command to include trailers in the commit message.
+ * Supports double-quoted, single-quoted, and unquoted message formats.
+ * Filters out trailers that already exist in the message.
+ * @param command - The git commit command to modify
+ * @param trailers - Record of trailers to append to the message
+ * @returns Modified command with trailers appended to the commit message
+ */
+export declare function modifyGitCommitCommand(command: string, trailers: Record<string, string>): string;

package/dist/modify-command.js

@@ -0,0 +1,72 @@
+import { isGitCommitCommand, extractCommitMessage } from "./git-commit.js";
+import { formatTrailers } from "./trailers.js";
+/**
+ * Escapes a string for use within $'...' ANSI-C quoting.
+ * @param str - String to escape
+ * @returns Escaped string safe for $'...' context
+ */
+export function escapeForAnsiCQuotes(str) {
+    return str
+        .replace(/\\/g, "\\\\") // Escape backslashes
+        .replace(/'/g, "\\'") // Escape single quotes
+        .replace(/\n/g, "\\n") // Convert newlines to \n escape sequence
+        .replace(/\r/g, "\\r") // Convert carriage returns to \r escape sequence
+        .replace(/\t/g, "\\t") // Convert tabs to \t escape sequence
+        // eslint-disable-next-line no-control-regex
+        .replace(/\x00/g, "\\x00"); // Convert null bytes to \x00 escape sequence
+}
+/**
+ * Filters out trailers that already exist in the commit message (case-insensitive).
+ * @param message - The commit message to check
+ * @param trailers - Record of trailers to filter
+ * @returns New trailers record with duplicates removed
+ */
+function filterDuplicateTrailers(message, trailers) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(trailers)) {
+        // Create a case-insensitive regex to match existing trailer
+        // Match "Key: value" format with the key capitalized
+        const capitalizedKey = key.charAt(0).toUpperCase() + key.slice(1);
+        const pattern = new RegExp(`^${capitalizedKey}: .+$`, "mi");
+        // Only add the trailer if it doesn't already exist in the message
+        if (!pattern.test(message)) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+/**
+ * Modifies a git commit command to include trailers in the commit message.
+ * Supports double-quoted, single-quoted, and unquoted message formats.
+ * Filters out trailers that already exist in the message.
+ * @param command - The git commit command to modify
+ * @param trailers - Record of trailers to append to the message
+ * @returns Modified command with trailers appended to the commit message
+ */
+export function modifyGitCommitCommand(command, trailers) {
+    if (!isGitCommitCommand(command)) {
+        return command;
+    }
+    if (Object.keys(trailers).length === 0) {
+        return command;
+    }
+    const message = extractCommitMessage(command);
+    if (!message) {
+        return command;
+    }
+    // Filter out trailers that already exist in the message
+    const newTrailers = filterDuplicateTrailers(message, trailers);
+    if (Object.keys(newTrailers).length === 0) {
+        return command;
+    }
+    const formattedTrailers = formatTrailers(newTrailers);
+    // Build the new message with trailers using ANSI-C quoting ($'...')
+    // This allows \n to be interpreted as actual newlines by the shell
+    const escapedMessage = escapeForAnsiCQuotes(message);
+    const escapedTrailers = escapeForAnsiCQuotes(formattedTrailers);
+    const newMessage = `${escapedMessage}\\n\\n${escapedTrailers}`;
+    // Replace the -m flag with $'...' syntax which interprets escape sequences
+    // Match any of: -m "..." or -m '...' or -m word
+    // Note: $$ in replacement string becomes a literal $ in the result
+    return command.replace(/-m\s+(?:"[^"]*"|'[^']*'|\S+)/, "-m $$'" + newMessage + "'");
+}

package/dist/trailers.d.ts

@@ -0,0 +1,16 @@
+import type { Variables } from "./types.js";
+/**
+ * Formats trailers into git trailer format.
+ * Each trailer is formatted as "Key: value" with the key capitalized.
+ * @param trailers - Record of trailer key-value pairs
+ * @returns Formatted trailers joined by newlines
+ */
+export declare function formatTrailers(trailers: Record<string, string>): string;
+/**
+ * Builds trailers by interpolating variables into trailer templates.
+ * Filters out empty values and uninterpolated variable placeholders.
+ * @param config - Record of trailer templates with variable placeholders
+ * @param variables - Record of variable values for interpolation
+ * @returns Record of trailers with interpolated values
+ */
+export declare function buildTrailers(config: Record<string, string>, variables: Variables): Record<string, string>;

package/dist/trailers.js

@@ -0,0 +1,33 @@
+import { interpolateVariables } from "./interpolate.js";
+/**
+ * Formats trailers into git trailer format.
+ * Each trailer is formatted as "Key: value" with the key capitalized.
+ * @param trailers - Record of trailer key-value pairs
+ * @returns Formatted trailers joined by newlines
+ */
+export function formatTrailers(trailers) {
+    const entries = [];
+    for (const [key, value] of Object.entries(trailers)) {
+        const formattedKey = key.charAt(0).toUpperCase() + key.slice(1);
+        entries.push(`${formattedKey}: ${value}`);
+    }
+    return entries.join("\n");
+}
+/**
+ * Builds trailers by interpolating variables into trailer templates.
+ * Filters out empty values and uninterpolated variable placeholders.
+ * @param config - Record of trailer templates with variable placeholders
+ * @param variables - Record of variable values for interpolation
+ * @returns Record of trailers with interpolated values
+ */
+export function buildTrailers(config, variables) {
+    const result = {};
+    for (const [key, template] of Object.entries(config)) {
+        const value = interpolateVariables(template, variables);
+        const trimmedValue = value.trim();
+        if (trimmedValue && !trimmedValue.match(/^\{\{.*\}\}$/)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared type definitions for the opencode-git-trailers plugin.
+ */
+/**
+ * Shell expression types accepted by Bun's shell API.
+ */
+export type ShellExpression = {
+    toString(): string;
+} | Array<ShellExpression> | string | {
+    raw: string;
+} | ReadableStream;
+/**
+ * Chainable shell command interface returned by ShellAPI.
+ */
+export interface ShellChain {
+    cwd(dir: string): ShellChain;
+    nothrow(): ShellChain;
+    quiet(): ShellChain;
+    text(): Promise<string>;
+}
+/**
+ * OpenCode's shell API for executing shell commands.
+ * The values parameter accepts the same types as Bun's shell API.
+ */
+export type ShellAPI = {
+    (strings: TemplateStringsArray, ...values: ShellExpression[]): ShellChain;
+};
+/**
+ * Variables used for template interpolation.
+ * Keys can be simple names (e.g., "model") or dot-separated paths (e.g., "user.name").
+ */
+export type Variables = Record<string, string | undefined>;

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared type definitions for the opencode-git-trailers plugin.
+ */
+export {};

package/dist/variables.d.ts

@@ -0,0 +1,18 @@
+import type { ShellAPI, Variables } from "./types.js";
+/**
+ * Retrieves user variables from git config.
+ * @param $shell - OpenCode's shell API
+ * @param cwd - Current working directory
+ * @returns Variables object with user.name and user.email
+ */
+export declare function getUserVariables($shell: ShellAPI, cwd: string): Promise<Variables>;
+/**
+ * Builds context variables from the current session and model information.
+ * @param context - Context object with optional model, provider, and session
+ * @returns Variables object with context information and current timestamp
+ */
+export declare function buildContextVariables(context: {
+    model?: string;
+    provider?: string;
+    session?: string;
+}): Variables;

package/dist/variables.js

@@ -0,0 +1,41 @@
+/**
+ * Retrieves user variables from git config.
+ * @param $shell - OpenCode's shell API
+ * @param cwd - Current working directory
+ * @returns Variables object with user.name and user.email
+ */
+export async function getUserVariables($shell, cwd) {
+    const name = await $shell `git config user.name`
+        .cwd(cwd)
+        .nothrow()
+        .quiet()
+        .text();
+    const email = await $shell `git config user.email`
+        .cwd(cwd)
+        .nothrow()
+        .quiet()
+        .text();
+    return {
+        "user.name": name.trim(),
+        "user.email": email.trim(),
+    };
+}
+/**
+ * Builds context variables from the current session and model information.
+ * @param context - Context object with optional model, provider, and session
+ * @returns Variables object with context information and current timestamp
+ */
+export function buildContextVariables(context) {
+    const variables = {};
+    if (context.model) {
+        variables.model = context.model;
+    }
+    if (context.provider) {
+        variables.provider = context.provider;
+    }
+    if (context.session) {
+        variables.session = context.session;
+    }
+    variables.timestamp = new Date().toISOString();
+    return variables;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "opencode-git-trailers",
+  "version": "0.1.1",
+  "description": "OpenCode plugin for managing git trailers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/ tests/",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@opencode-ai/plugin": "^1.2.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.2.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lannuttia/opencode-git-trailers.git"
+  },
+  "author": "Anthony Lannutti <lannuttia@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/lannuttia/opencode-git-trailers#readme",
+  "bugs": "https://github.com/lannuttia/opencode-git-trailers/issues",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "git",
+    "git-trailers",
+    "ai",
+    "coding-assistant",
+    "plugin"
+  ],
+  "dependencies": {}
+}