feat(services): add commit, conventional, hooks, and VCS logic

- Add commit-service for commit planning and message generation
- Implement conventional commit message validation
- Add gitignore-service for generating and merging .gitignore files
- Create hooks service for executing and installing commit hooks
- Add openai-client for LLM interaction and commit message generation
- Implement scope-service for auto-generating project scopes
- Implement vcs service supporting Git and Jj with diff and commit operations
- Add tests for conventional commit validation and hook execution

This commit introduces several core service modules to support commit message
automation and repository management. The commit-service handles commit planning,
message generation, and performing commits with support for Git and Jj. The
conventional module validates commit messages against conventional commit rules.
The hooks service runs configured commit hooks including shell and conventional
validation hooks. The openai-client integrates with an LLM to generate commit
messages, plans, and scopes. The gitignore-service generates .gitignore files
based on detected project technologies. The scope-service derives commit scopes
from the project history and structure. Finally, the vcs service abstracts
version control operations for Git and Jj. Tests validate commit message
validation and hook execution. These additions establish a foundation for
automated, consistent commit workflows.

Co-Authored-By: Git Agent <noreply@git-agent.dev>

Author: xesrevinu

src/services/commit-service.ts

@@ -0,0 +1,172 @@
+import { wrapExplanation } from "../shared/text";
+
+export interface ValidationIssue {
+  readonly severity: "error" | "warning";
+  readonly message: string;
+}
+
+export interface ValidationResult {
+  readonly issues: ReadonlyArray<ValidationIssue>;
+}
+
+const headerRegex =
+  /^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\([a-z0-9_-]+\))?!?: .+/;
+const coAuthorRegex = /^Co-Authored-By: .+ <[^>]+@[^>]+>$/;
+const footerRegex = /^([A-Za-z][A-Za-z0-9-]*|BREAKING CHANGE): /;
+const pastVerbs = new Set([
+  "added",
+  "removed",
+  "updated",
+  "changed",
+  "fixed",
+  "created",
+  "deleted",
+  "modified",
+  "implemented",
+  "refactored",
+  "renamed",
+  "moved",
+  "replaced",
+  "improved",
+  "enhanced",
+  "upgraded",
+  "downgraded",
+  "reverted",
+  "resolved",
+]);
+
+export const validateConventional = (raw: string): ValidationResult => {
+  const issues: Array<ValidationIssue> = [];
+  if (raw.trim().length === 0) {
+    return { issues: [{ severity: "error", message: "commit message is empty" }] };
+  }
+
+  const lines = raw.split("\n");
+  const header = lines[0] ?? "";
+
+  if (!headerRegex.test(header)) {
+    issues.push({
+      severity: "error",
+      message:
+        "header must match: <type>[(<scope>)][!]: <description> (valid types: feat fix docs style refactor perf test chore build ci revert)",
+    });
+  }
+  if (header.length > 50) {
+    issues.push({
+      severity: "error",
+      message: `title must be 50 characters or less (got ${header.length})`,
+    });
+  }
+  if (header.endsWith(".")) {
+    issues.push({
+      severity: "error",
+      message: "title must not end with a period",
+    });
+  }
+
+  const separatorIndex = header.indexOf(": ");
+  if (separatorIndex >= 0) {
+    const description = header.slice(separatorIndex + 2);
+    if (description !== description.toLowerCase()) {
+      issues.push({
+        severity: "error",
+        message: "description must be all lowercase",
+      });
+    }
+    const firstWord = description.trim().split(/\s+/)[0] ?? "";
+    if (pastVerbs.has(firstWord)) {
+      issues.push({
+        severity: "warning",
+        message: `description starts with past-tense verb "${firstWord}" - prefer imperative mood`,
+      });
+    }
+  }
+
+  if (lines.length < 3) {
+    issues.push({
+      severity: "error",
+      message: "body is required: add bullet points followed by an explanation paragraph",
+    });
+    return { issues };
+  }
+  if ((lines[1] ?? "") !== "") {
+    issues.push({
+      severity: "error",
+      message: "blank line required between header and body",
+    });
+  }
+
+  const bodyLines = lines.slice(2);
+  let lastBulletIndex = -1;
+  const bulletFirstWords: Array<string> = [];
+
+  for (const [index, line] of bodyLines.entries()) {
+    if (line.startsWith("- ")) {
+      lastBulletIndex = index;
+      const firstWord = line.slice(2).trim().split(/\s+/)[0] ?? "";
+      if (firstWord.length > 0) {
+        bulletFirstWords.push(firstWord.toLowerCase());
+      }
+    }
+  }
+
+  if (lastBulletIndex === -1) {
+    issues.push({
+      severity: "error",
+      message: "body must contain at least one bullet point starting with '- '",
+    });
+  } else {
+    const hasExplanation = bodyLines.slice(lastBulletIndex + 1).some((line) => {
+      const trimmed = line.trim();
+      return trimmed.length > 0 && !footerRegex.test(trimmed) && !trimmed.startsWith("- ");
+    });
+    if (!hasExplanation) {
+      issues.push({
+        severity: "error",
+        message: "explanation paragraph required after bullet points",
+      });
+    }
+  }
+
+  for (const line of bodyLines) {
+    if (footerRegex.test(line)) {
+      continue;
+    }
+    if (line.length > 72) {
+      issues.push({
+        severity: "error",
+        message: `body line exceeds 72 characters: ${line}`,
+      });
+    }
+    if (line.startsWith("Co-Authored-By: ") && !coAuthorRegex.test(line)) {
+      issues.push({
+        severity: "error",
+        message: "Co-Authored-By footer must match 'Co-Authored-By: Name <email@example.com>'",
+      });
+    }
+  }
+
+  for (const word of bulletFirstWords) {
+    if (pastVerbs.has(word)) {
+      issues.push({
+        severity: "warning",
+        message: `bullet starts with past-tense verb "${word}" - prefer imperative mood`,
+      });
+    }
+  }
+
+  return {
+    issues,
+  };
+};
+
+export const hasErrors = (result: ValidationResult): boolean =>
+  result.issues.some((issue) => issue.severity === "error");
+
+export const validationErrors = (result: ValidationResult): Array<string> =>
+  result.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
+
+export const validationWarnings = (result: ValidationResult): Array<string> =>
+  result.issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message);
+
+export const normalizeExplanation = (text: string): string => wrapExplanation(text, 72);

src/services/conventional.ts

@@ -0,0 +1,163 @@
+import { platform } from "node:os";
+import { Effect, FileSystem, Path } from "effect";
+import { ApiError } from "../shared/errors";
+import { buildEnvironment } from "../config/env";
+import { detectTechnologies, type ProviderConfig } from "./openai-client";
+import type { VcsClient } from "./vcs";
+
+const autoGenStart = "### git-agent auto-generated — DO NOT EDIT this block ###";
+const legacyAutoGenStart = "### git-agent auto-generated - DO NOT EDIT this block ###";
+const autoGenEnd = "### end git-agent ###";
+const customSection = "### custom rules ###";
+
+const runtimeOs = (): string => {
+  switch (platform()) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    default:
+      return "linux";
+  }
+};
+
+const wrapGenerated = (content: string, technologies: ReadonlyArray<string>): string =>
+  `${autoGenStart}\n# Technologies: ${technologies.join(", ")}\n${content.trimEnd()}\n${autoGenEnd}\n`;
+
+const toptalTechs = (content: string): Array<string> => {
+  for (const line of content.split("\n").slice(0, 10)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("# Created by")) {
+      continue;
+    }
+    const fields = trimmed.split(/\s+/);
+    const url = fields[fields.length - 1];
+    if (url == null) {
+      break;
+    }
+    const marker = "/api/";
+    const index = url.lastIndexOf(marker);
+    if (index !== -1) {
+      return url
+        .slice(index + marker.length)
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    }
+    break;
+  }
+  return [];
+};
+
+const mergeGitignore = (existing: string, generated: string): string => {
+  const userLines: Array<string> = [];
+  let insideBlock = false;
+
+  for (const line of existing.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === autoGenStart || trimmed === legacyAutoGenStart) {
+      insideBlock = true;
+      continue;
+    }
+    if (trimmed === autoGenEnd) {
+      insideBlock = false;
+      continue;
+    }
+    if (trimmed === customSection) {
+      continue;
+    }
+    if (!insideBlock) {
+      userLines.push(line);
+    }
+  }
+
+  const covered = new Set(
+    generated
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith("#")),
+  );
+
+  const unique = userLines.filter((line) => {
+    const trimmed = line.trim();
+    return trimmed.length === 0 || trimmed.startsWith("#") || !covered.has(trimmed);
+  });
+
+  while (unique.length > 0 && unique[0]?.trim().length === 0) {
+    unique.shift();
+  }
+  while (unique.length > 0 && unique[unique.length - 1]?.trim().length === 0) {
+    unique.pop();
+  }
+
+  if (unique.length === 0) {
+    return generated;
+  }
+  return `${generated.trimEnd()}\n\n${customSection}\n${unique.join("\n")}\n`;
+};
+
+const fetchGitignore = (technologies: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const env = yield* buildEnvironment;
+    const baseUrl = env.gitignoreBaseUrl.replace(/\/$/, "");
+    return yield* Effect.tryPromise({
+      try: async () => {
+        const response = await fetch(
+          `${baseUrl}/${technologies.map((item) => encodeURIComponent(item)).join(",")}`,
+        );
+        const text = await response.text();
+        if (!response.ok) {
+          throw new ApiError({
+            message: `failed to fetch gitignore template (${response.status})`,
+            status: response.status,
+            body: text,
+          });
+        }
+        return text;
+      },
+      catch: (cause) =>
+        cause instanceof ApiError
+          ? cause
+          : new ApiError({
+              message: cause instanceof Error ? cause.message : String(cause),
+            }),
+    });
+  });
+
+export const generateGitignore = (provider: ProviderConfig, vcs: VcsClient, cwd: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const [dirs, files] = yield* Effect.all([vcs.topLevelDirs(cwd), vcs.projectFiles(cwd)]);
+    let technologies = yield* detectTechnologies(provider, runtimeOs(), dirs, files);
+    const fetched = yield* fetchGitignore(technologies);
+    const actualTechnologies = toptalTechs(fetched);
+    if (actualTechnologies.length > 0) {
+      technologies = actualTechnologies;
+    }
+
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const existing = yield* fs.exists(gitignorePath).pipe(
+      Effect.flatMap((exists) =>
+        exists ? fs.readFileString(gitignorePath, "utf8") : Effect.succeed(""),
+      ),
+      Effect.mapError(
+        (cause) =>
+          new ApiError({
+            message: `failed to write .gitignore: ${cause.message}`,
+          }),
+      ),
+    );
+    const generated = wrapGenerated(fetched, technologies);
+    const content = existing.length === 0 ? generated : mergeGitignore(existing, generated);
+
+    yield* fs.writeFileString(gitignorePath, content, { mode: 0o644 }).pipe(
+      Effect.mapError(
+        (cause) =>
+          new ApiError({
+            message: `failed to write .gitignore: ${cause.message}`,
+          }),
+      ),
+    );
+    return technologies;
+  });