zencommit 0.1.0

package/src/llm/generate.ts

@@ -0,0 +1,188 @@
+import { generateObject, generateText, jsonSchema } from 'ai';
+import { resolveProviderAuth, resolveRuntimeSecrets } from '../auth/secrets.js';
+import { getVerbosity, logVerbose } from '../util/logger.js';
+import { resolveLanguageModel } from './providers.js';
+
+export interface CommitMessage {
+  subject: string;
+  body: string;
+}
+
+export interface GenerateInput {
+  modelId: string;
+  system: string;
+  user: string;
+  temperature: number;
+  maxOutputTokens: number;
+  timeoutMs: number;
+  maxSubjectChars: number;
+  style: 'conventional' | 'freeform';
+  openaiCompatible?: {
+    baseUrl?: string;
+    name?: string;
+  };
+}
+
+export interface GenerateDeps {
+  callModel?: (input: GenerateInput) => Promise<CommitMessage>;
+}
+
+const COMMIT_SCHEMA = jsonSchema<CommitMessage>({
+  type: 'object',
+  properties: {
+    subject: { type: 'string' },
+    body: { type: 'string' },
+  },
+  required: ['subject', 'body'],
+  additionalProperties: false,
+});
+
+const withTimeout = async <T>(promise: Promise<T>, timeoutMs: number): Promise<T> => {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return promise;
+  }
+  return await Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error('Model call timed out')), timeoutMs),
+    ),
+  ]);
+};
+
+const normalizeOutput = (value: string): string => value.replace(/\r\n/g, '\n').trim();
+
+const resolveModel = (modelId: string, input: GenerateInput) =>
+  resolveLanguageModel(modelId, { openaiCompatible: input.openaiCompatible });
+
+const ensureAuth = async (modelId: string): Promise<void> => {
+  const auth = resolveProviderAuth(modelId);
+  if (!auth) {
+    return;
+  }
+  if (getVerbosity() >= 2) {
+    logVerbose(2, `auth: provider ${auth.id}, keys=${auth.envKeys.join(', ')}`);
+  }
+  const secrets = await resolveRuntimeSecrets(auth.envKeys);
+  const foundKeys = Object.keys(secrets);
+  for (const [key, value] of Object.entries(secrets)) {
+    process.env[key] = value;
+  }
+  if (auth.required && foundKeys.length === 0) {
+    const primary = auth.primaryEnvKey ?? auth.envKeys[0] ?? auth.id;
+    throw new Error(`Missing API key for ${primary}`);
+  }
+};
+
+const callModelOnce = async (
+  input: GenerateInput,
+  strictSubject = false,
+): Promise<CommitMessage> => {
+  await ensureAuth(input.modelId);
+  const model = resolveModel(input.modelId, input);
+  const userPrompt = strictSubject
+    ? `${input.user}\nSubject must be <= ${input.maxSubjectChars} characters.`
+    : input.user;
+
+  try {
+    const result = await withTimeout(
+      generateObject({
+        model,
+        schema: COMMIT_SCHEMA,
+        messages: [
+          { role: 'system', content: input.system },
+          { role: 'user', content: userPrompt },
+        ],
+        temperature: input.temperature,
+        maxTokens: input.maxOutputTokens,
+      }),
+      input.timeoutMs,
+    );
+    return {
+      subject: normalizeOutput(result.object.subject ?? ''),
+      body: normalizeOutput(result.object.body ?? ''),
+    };
+  } catch {
+    if (getVerbosity() >= 2) {
+      logVerbose(2, 'llm: structured output failed, falling back to text');
+    }
+    const textResult = await withTimeout(
+      generateText({
+        model,
+        messages: [
+          { role: 'system', content: input.system },
+          { role: 'user', content: userPrompt },
+        ],
+        temperature: input.temperature,
+        maxTokens: input.maxOutputTokens,
+      }),
+      input.timeoutMs,
+    );
+
+    const rawText = textResult.text ?? '';
+    try {
+      const parsed = JSON.parse(rawText) as CommitMessage;
+      return {
+        subject: normalizeOutput(parsed.subject ?? ''),
+        body: normalizeOutput(parsed.body ?? ''),
+      };
+    } catch {
+      if (getVerbosity() >= 2) {
+        logVerbose(2, 'llm: JSON parse failed, attempting repair');
+      }
+      const repairPrompt = `${userPrompt}\nReturn ONLY valid JSON matching the schema.`;
+      const repairResult = await withTimeout(
+        generateText({
+          model,
+          messages: [
+            { role: 'system', content: input.system },
+            { role: 'user', content: repairPrompt },
+          ],
+          temperature: input.temperature,
+          maxTokens: input.maxOutputTokens,
+        }),
+        input.timeoutMs,
+      );
+      const repaired = JSON.parse(repairResult.text ?? '') as CommitMessage;
+      return {
+        subject: normalizeOutput(repaired.subject ?? ''),
+        body: normalizeOutput(repaired.body ?? ''),
+      };
+    }
+  }
+};
+
+export const generateCommitMessage = async (
+  input: GenerateInput,
+  deps: GenerateDeps = {},
+): Promise<CommitMessage> => {
+  if (process.env.ZENCOMMIT_MOCK_RESPONSE) {
+    if (getVerbosity() >= 2) {
+      logVerbose(2, 'llm: using mock response');
+    }
+    const mocked = JSON.parse(process.env.ZENCOMMIT_MOCK_RESPONSE) as CommitMessage;
+    return {
+      subject: normalizeOutput(mocked.subject ?? ''),
+      body: normalizeOutput(mocked.body ?? ''),
+    };
+  }
+
+  const callModel = deps.callModel ?? callModelOnce;
+  let result = await callModel(input);
+
+  if (result.subject.length > input.maxSubjectChars) {
+    result = await callModel({
+      ...input,
+      user: `${input.user}\nKeep subject <= ${input.maxSubjectChars} chars.`,
+    });
+  }
+
+  if (result.subject.length > input.maxSubjectChars) {
+    const trimmed = result.subject.slice(0, Math.max(0, input.maxSubjectChars - 3));
+    result.subject = `${trimmed}...`;
+  }
+
+  result.subject = normalizeOutput(result.subject);
+  result.body = normalizeOutput(result.body ?? '');
+
+  return result;
+};

package/src/llm/prompt-template.ts

@@ -0,0 +1,44 @@
+export type TemplateValue = string | number | boolean | null | undefined;
+
+export type TemplateContext = Record<string, TemplateValue>;
+
+const isTruthy = (value: TemplateValue): boolean => {
+  if (value === null || value === undefined || value === false) {
+    return false;
+  }
+  if (typeof value === 'string') {
+    return value.trim().length > 0;
+  }
+  return true;
+};
+
+const normalizeValue = (value: TemplateValue): string => {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return String(value);
+};
+
+export const renderTemplate = (template: string, context: TemplateContext): string => {
+  let result = template;
+
+  const conditionalPattern = /{{#if\s+([\w.-]+)\s*}}([\s\S]*?){{\/if}}/g;
+  while (true) {
+    const next = result.replace(conditionalPattern, (_, key: string, inner: string) => {
+      const value = context[key];
+      return isTruthy(value) ? inner : '';
+    });
+    if (next === result) {
+      break;
+    }
+    result = next;
+  }
+
+  const variablePattern = /{{\s*([\w.-]+)\s*}}/g;
+  result = result.replace(variablePattern, (_, key: string) => normalizeValue(context[key]));
+
+  return result;
+};
+
+export const normalizePrompt = (value: string): string =>
+  value.replace(/\r\n/g, '\n').trim();

package/src/llm/prompt.ts

@@ -0,0 +1,83 @@
+import { normalizePrompt, renderTemplate } from './prompt-template.js';
+
+export interface PromptInput {
+  style: 'conventional' | 'freeform';
+  language: string;
+  includeBody: boolean;
+  emoji: boolean;
+  maxSubjectChars: number;
+  fileList: string;
+  diffText: string;
+}
+
+export interface PromptOutput {
+  system: string;
+  user: string;
+}
+
+const templateCache = new Map<string, string>();
+
+const loadTemplate = async (name: string): Promise<string> => {
+  const cached = templateCache.get(name);
+  if (cached) {
+    return cached;
+  }
+  const url = new URL(`./prompts/${name}.md`, import.meta.url);
+  const text = await Bun.file(url).text();
+  templateCache.set(name, text);
+  return text;
+};
+
+const renderMarkdown = (value: string): void => {
+  const renderer = (Bun as unknown as { markdown?: { render?: (input: string) => string } })
+    .markdown?.render;
+  if (typeof renderer !== 'function') {
+    return;
+  }
+  try {
+    renderer(value);
+  } catch {
+    // Ignore markdown parser errors and keep raw markdown.
+  }
+};
+
+const buildUserPrompt = async (input: PromptInput, includeDiff: boolean): Promise<string> => {
+  const baseTemplate = await loadTemplate('base');
+  const conventionalTemplate = await loadTemplate('conventional');
+  const gitmojiTemplate = await loadTemplate('gitmoji');
+
+  const fileListBlock = input.fileList.trim().length > 0 ? input.fileList.trim() : '(omitted)';
+  const diffBlock = includeDiff
+    ? input.diffText.trim().length > 0
+      ? input.diffText.trim()
+      : '(empty)'
+    : '(omitted for budgeting)';
+
+  const includeBodyGuideline = input.includeBody
+    ? 'Include a short body (1-3 bullets or 1 short paragraph) expanding on intent or impact.'
+    : 'Do not include a body; set "body" to an empty string.';
+
+  const markdown = renderTemplate(baseTemplate, {
+    language: input.language,
+    maxSubjectChars: input.maxSubjectChars,
+    includeBodyGuideline,
+    fileListBlock,
+    diffBlock,
+    conventionalGuidelines: input.style === 'conventional' ? conventionalTemplate.trim() : '',
+    gitmojiGuidelines: input.emoji ? gitmojiTemplate.trim() : '',
+  });
+
+  const normalized = normalizePrompt(markdown);
+  renderMarkdown(normalized);
+  return normalized;
+};
+
+export const buildPrompt = async (input: PromptInput): Promise<PromptOutput> => ({
+  system: normalizePrompt(await loadTemplate('system')),
+  user: await buildUserPrompt(input, true),
+});
+
+export const buildPromptWithoutDiff = async (input: PromptInput): Promise<PromptOutput> => ({
+  system: normalizePrompt(await loadTemplate('system')),
+  user: await buildUserPrompt(input, false),
+});

package/src/llm/prompts/base.md

@@ -0,0 +1,119 @@
+## Commit Message Guidelines
+
+### Subject Line Requirements
+
+1. **Imperative mood**: Write as a command - "add feature" not "added feature" or "adding feature".
+2. **Present tense**: Describe what applying the commit does, not what you did.
+3. **No period**: Do not end the subject with a period or any punctuation.
+4. **Concise**: Stay within {{maxSubjectChars}} characters - be specific but brief.
+5. **Informative**: A reader should understand the change's purpose without viewing the diff.
+
+### Writing Style
+
+- **Be specific**: "fix null pointer in user validation" is better than "fix bug".
+- **Describe intent**: Focus on _why_ the change matters, not _what_ files changed.
+- **Avoid vague terms**: Don't use "update", "change", "modify" without context - specify what was updated and why.
+- **No file paths**: Don't list filenames - summarize the logical change instead.
+- **No code snippets**: Don't include code, function names, or variable names unless absolutely essential for understanding.
+
+### What NOT to Include
+
+- Implementation details (the diff shows this)
+- File names or paths (unless the change is specifically about renaming/moving)
+- Line numbers or code references
+- Ticket/issue numbers (these belong in the body or are added separately)
+- Timestamps or dates
+- Author information
+- Phrases like "This commit..." or "Changes include..."
+
+### Analyzing the Diff
+
+When reading the diff to write the commit message:
+
+1. **Identify the primary change**: What is the main purpose? Bug fix, new feature, refactor?
+2. **Look for patterns**: Are multiple files changed for the same reason?
+3. **Check for side effects**: Are there secondary changes (cleanup, formatting) alongside the main change?
+4. **Consider impact**: How does this change affect users, developers, or the system?
+
+If changes span multiple concerns, focus on the most significant one in the subject and mention others in the body (if body is enabled).
+
+---
+
+{{#if conventionalGuidelines}}
+
+## Conventional Commits
+
+{{conventionalGuidelines}}
+
+---
+
+{{/if}}
+
+{{#if gitmojiGuidelines}}
+
+## Gitmoji
+
+{{gitmojiGuidelines}}
+
+---
+
+{{/if}}
+
+## Body Guidelines
+
+{{includeBodyGuideline}}
+
+When writing a body:
+
+- Separate from subject with a blank line
+- Explain the motivation for the change
+- Contrast with previous behavior if relevant
+- Use bullet points for multiple related changes
+- Keep each line reasonably short (aim for ~72 characters)
+- Focus on "why" rather than "what" (the diff shows what)
+
+---
+
+## Input Context
+
+### Files Changed
+
+The following files were modified in this commit:
+
+{{fileListBlock}}
+
+### Diff Content
+
+{{diffBlock}}
+
+---
+
+## Output Requirements
+
+Generate a JSON object with exactly two keys:
+
+```json
+{
+  "subject": "<the commit subject line>",
+  "body": "<the commit body, or empty string if no body>"
+}
+```
+
+### Validation Checklist
+
+Before outputting, verify:
+
+- [ ] Subject is {{maxSubjectChars}} characters or fewer
+- [ ] Subject uses imperative mood ("add" not "added")
+- [ ] Subject has no trailing period
+- [ ] Subject describes the actual changes in the diff (no fabrication)
+- [ ] Body is empty string if body is disabled, or meaningful content if enabled
+- [ ] Output is valid JSON with no extra text, markdown, or formatting
+- [ ] Language is {{language}}
+
+### Critical Rules
+
+1. **Output ONLY the JSON object** - no markdown code fences, no explanations, no preamble.
+2. **Never fabricate changes** - only describe what's actually in the diff.
+3. **Never exceed the character limit** - truncate intelligently if needed, don't just cut off.
+4. **Use the exact JSON format** - both keys must be present, body must be empty string (not null) when unused.

package/src/llm/prompts/conventional.md

@@ -0,0 +1,123 @@
+Follow the Conventional Commits specification (v1.0.0) precisely.
+
+### Format
+
+```
+<type>[optional scope][!]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+For this tool, output only the subject line in "subject" and the body (if requested) in "body".
+
+### Structure Rules
+
+1. **Type** (required): A noun describing the category of change. Must be lowercase.
+2. **Scope** (optional): A noun in parentheses describing the section of the codebase (e.g., `feat(parser):`).
+3. **Breaking change indicator** (optional): A `!` immediately before the `:` signals a breaking change.
+4. **Description** (required): A short summary immediately after the colon and space.
+5. **Body** (optional): Free-form text providing additional context, separated from subject by a blank line.
+
+### Allowed Types
+
+Choose the single most appropriate type based on the primary purpose of the change:
+
+| Type       | Description                                                               |
+| ---------- | ------------------------------------------------------------------------- |
+| `feat`     | A new feature visible to users or a significant capability addition       |
+| `fix`      | A bug fix that corrects incorrect behavior                                |
+| `docs`     | Documentation-only changes (README, comments, JSDoc, etc.)                |
+| `style`    | Code style/formatting changes that do not affect logic (whitespace, etc.) |
+| `refactor` | Code restructuring that neither fixes a bug nor adds a feature            |
+| `perf`     | Performance improvements without functional changes                       |
+| `test`     | Adding, updating, or fixing tests (no production code changes)            |
+| `build`    | Changes to build system, dependencies, or tooling (npm, webpack, etc.)    |
+| `ci`       | Changes to CI/CD configuration (GitHub Actions, Jenkins, etc.)            |
+| `chore`    | Maintenance tasks that don't fit other categories (deps update, cleanup)  |
+| `revert`   | Reverts a previous commit (reference the reverted commit in body)         |
+
+### Type Selection Guidelines
+
+- **feat vs refactor**: If the change adds new behavior users can observe, it's `feat`. If it restructures existing code without changing behavior, it's `refactor`.
+- **fix vs refactor**: If the code was broken and now works correctly, it's `fix`. If the code worked before and still works the same way, it's `refactor`.
+- **chore vs build**: Build system changes (webpack config, tsconfig) use `build`. Generic maintenance (updating .gitignore, cleaning up old files) uses `chore`.
+- **docs vs style**: Changes to documentation/comments use `docs`. Formatting changes to code itself use `style`.
+
+### Scope Guidelines
+
+- Use lowercase, kebab-case for scopes (e.g., `feat(user-auth):`, `fix(api-client):`).
+- Scope should identify the module, component, or area affected.
+- Common scopes: `api`, `ui`, `cli`, `config`, `core`, `deps`, `auth`, `db`, module names, component names.
+- Omit scope if the change is broad or the scope is obvious from context.
+- Be consistent with scopes used in the repository's existing commit history.
+
+### Description Rules
+
+1. Use imperative, present-tense verbs: "add", "fix", "update", "remove", "refactor" (not "added", "fixes", "updating").
+2. Start with a lowercase letter (unless it's a proper noun or acronym).
+3. Do not end with a period.
+4. Be specific but concise - aim for clarity in under 50 characters when possible (hard limit is the configured max).
+5. Describe _what_ the commit does when applied, not what you did.
+
+### Breaking Changes
+
+If the commit introduces a breaking change (incompatible API change, removed feature, etc.):
+
+- Add `!` before the colon: `feat(api)!: remove deprecated endpoints`
+- Optionally explain in the body with `BREAKING CHANGE: <explanation>`
+
+### Examples
+
+**Simple feature:**
+
+```
+feat(auth): add OAuth2 login support
+```
+
+**Bug fix with scope:**
+
+```
+fix(parser): handle empty input without throwing
+```
+
+**Refactor without scope:**
+
+```
+refactor: extract validation logic into separate module
+```
+
+**Breaking change:**
+
+```
+feat(api)!: change response format to JSON:API spec
+```
+
+**Documentation:**
+
+```
+docs: update installation instructions for Windows
+```
+
+**Build/dependencies:**
+
+```
+build(deps): upgrade TypeScript to v5.3
+```
+
+**Chore:**
+
+```
+chore: remove unused development scripts
+```
+
+**With body (when body is enabled):**
+
+```
+fix(cache): prevent stale data on concurrent requests
+
+Race condition occurred when multiple requests invalidated
+the cache simultaneously. Added mutex lock to ensure
+atomic read-modify-write operations.
+```