juliusmarminge · Mar 3, 2026 · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -18,11 +18,16 @@ This repository is a VERY EARLY WIP. Proposing sweeping changes that improve lon
 
 If a tradeoff is required, choose correctness and robustness over short-term convenience.
 
+## Maintainability
+
+Long term maintainability is a core priority. If you add new functionality, first check if there are shared logic that can be extracted to a separate module. Duplicate logic across mulitple files is a code smell and should be avoided. Don't be afraid to change existing code. Don't take shortcuts by just adding local logic to solve a problem.
+
 ## Package Roles
 
 - `apps/server`: Node.js WebSocket server. Wraps Codex app-server (JSON-RPC over stdio), serves the React web app, and manages provider sessions.
 - `apps/web`: React/Vite UI. Owns session UX, conversation/event rendering, and client-side state. Connects to the server via WebSocket.
-- `packages/contracts`: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types.
+- `packages/contracts`: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. Keep this package schema-only — no runtime logic.
+- `packages/shared`: Shared runtime utilities consumed by both server and web. Uses explicit subpath exports (e.g. `@t3tools/shared/git`) — no barrel index.
 
 ## Codex App Server (Important)
 

diff --git a/apps/server/package.json b/apps/server/package.json
@@ -30,6 +30,7 @@
     "@effect/language-service": "0.75.1",
     "@effect/vitest": "catalog:",
     "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "workspace:*",
     "@t3tools/web": "workspace:*",
     "@types/bun": "^1.3.9",
     "@types/node": "^24.10.13",

diff --git a/apps/server/src/git/Layers/CodexTextGeneration.test.ts b/apps/server/src/git/Layers/CodexTextGeneration.test.ts
@@ -189,14 +189,15 @@ function withFakeCodexEnv<A, E, R>(
 const CodexTextGenerationTestLayer = makeCodexTextGenerationTestLayer(process.cwd());
 
 it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
-  it.effect("generates and sanitizes commit messages", () =>
+  it.effect("generates and sanitizes commit messages without branch by default", () =>
     withFakeCodexEnv(
       {
         output: JSON.stringify({
           subject:
             "  Add important change to the system with too much detail and a trailing period.\nsecondary line",
           body: "\n- added migration\n- updated tests\n",
         }),
+        stdinMustNotContain: "branch must be a short semantic git branch fragment",
       },
       Effect.gen(function* () {
         const textGeneration = yield* TextGeneration;
@@ -211,6 +212,34 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         expect(generated.subject.length).toBeLessThanOrEqual(72);
         expect(generated.subject.endsWith(".")).toBe(false);
         expect(generated.body).toBe("- added migration\n- updated tests");
+        expect(generated.branch).toBeUndefined();
+      }),
+    ),
+  );
+
+  it.effect("generates commit message with branch when includeBranch is true", () =>
+    withFakeCodexEnv(
+      {
+        output: JSON.stringify({
+          subject: "Add important change",
+          body: "",
+          branch: "fix/important-system-change",
+        }),
+        stdinMustContain: "branch must be a short semantic git branch fragment",
+      },
+      Effect.gen(function* () {
+        const textGeneration = yield* TextGeneration;
+
+        const generated = yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/codex-effect",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          includeBranch: true,
+        });
+
+        expect(generated.subject).toBe("Add important change");
+        expect(generated.branch).toBe("feature/fix/important-system-change");
       }),
     ),
   );

diff --git a/apps/server/src/git/Layers/CodexTextGeneration.ts b/apps/server/src/git/Layers/CodexTextGeneration.ts
@@ -3,6 +3,8 @@ import { randomUUID } from "node:crypto";
 import { Effect, FileSystem, Layer, Option, Path, Schema, Stream } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
+import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
+
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import { TextGenerationError } from "../Errors.ts";
@@ -93,24 +95,6 @@ function sanitizePrTitle(raw: string): string {
   return "Update project changes";
 }
 
-function sanitizeBranchName(raw: string): string {
-  const normalized = raw
-    .trim()
-    .toLowerCase()
-    .replace(/['"`]/g, "")
-    .replace(/^[./\s_-]+|[./\s_-]+$/g, "");
-
-  const branchFragment = normalized
-    .replace(/[^a-z0-9/_-]+/g, "-")
-    .replace(/\/+/g, "/")
-    .replace(/-+/g, "-")
-    .replace(/^[./_-]+|[./_-]+$/g, "")
-    .slice(0, 64)
-    .replace(/[./_-]+$/g, "");
-
-  return branchFragment.length > 0 ? branchFragment : "update";
-}
-
 const makeCodexTextGeneration = Effect.gen(function* () {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -328,12 +312,19 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     });
 
   const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = (input) => {
+    const wantsBranch = input.includeBranch === true;
+
     const prompt = [
       "You write concise git commit messages.",
-      "Return a JSON object with keys: subject, body.",
+      wantsBranch
+        ? "Return a JSON object with keys: subject, body, branch."
+        : "Return a JSON object with keys: subject, body.",
       "Rules:",
       "- subject must be imperative, <= 72 chars, and no trailing period",
       "- body can be empty string or short bullet points",
+      ...(wantsBranch
+        ? ["- branch must be a short semantic git branch fragment for this change"]
+        : []),
       "- capture the primary user-visible or developer-visible change",
       "",
       `Branch: ${input.branch ?? "(detached)"}`,
@@ -345,20 +336,31 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       limitSection(input.stagedPatch, 40_000),
     ].join("\n");
 
+    const outputSchemaJson = wantsBranch
+      ? Schema.Struct({
+          subject: Schema.String,
+          body: Schema.String,
+          branch: Schema.String,
+        })
+      : Schema.Struct({
+          subject: Schema.String,
+          body: Schema.String,
+        });
+
     return runCodexJson({
       operation: "generateCommitMessage",
       cwd: input.cwd,
       prompt,
-      outputSchemaJson: Schema.Struct({
-        subject: Schema.String,
-        body: Schema.String,
-      }),
+      outputSchemaJson,
     }).pipe(
       Effect.map(
         (generated) =>
           ({
             subject: sanitizeCommitSubject(generated.subject),
             body: generated.body.trim(),
+            ...("branch" in generated && typeof generated.branch === "string"
+              ? { branch: sanitizeFeatureBranchName(generated.branch) }
+              : {}),
           }) satisfies CommitMessageGenerationResult,
       ),
     );
@@ -408,7 +410,10 @@ const makeCodexTextGeneration = Effect.gen(function* () {
 
   const generateBranchName: TextGenerationShape["generateBranchName"] = (input) => {
     return Effect.gen(function* () {
-      const { imagePaths } = yield* materializeImageAttachments("generateBranchName", input.attachments);
+      const { imagePaths } = yield* materializeImageAttachments(
+        "generateBranchName",
+        input.attachments,
+      );
       const attachmentLines = (input.attachments ?? []).map(
         (attachment) =>
           `- ${attachment.name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes)`,
@@ -446,7 +451,7 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       });
 
       return {
-        branch: sanitizeBranchName(generated.branch),
+        branch: sanitizeBranchFragment(generated.branch),
       } satisfies BranchNameGenerationResult;
     });
   };

diff --git a/apps/server/src/git/Layers/GitCore.test.ts b/apps/server/src/git/Layers/GitCore.test.ts
@@ -110,6 +110,7 @@ const makeIsolatedGitCore = (gitService: GitServiceShape) =>
       createBranch: (input) => core.createBranch(input),
       checkoutBranch: (input) => core.checkoutBranch(input),
       initRepo: (input) => core.initRepo(input),
+      listLocalBranchNames: (cwd) => core.listLocalBranchNames(cwd),
     } satisfies GitCoreShape;
   });
 

diff --git a/apps/server/src/git/Layers/GitCore.ts b/apps/server/src/git/Layers/GitCore.ts
@@ -1172,6 +1172,20 @@ const makeGitCore = Effect.gen(function* () {
       fallbackErrorMessage: "git init failed",
     }).pipe(Effect.asVoid);
 
+  const listLocalBranchNames: GitCoreShape["listLocalBranchNames"] = (cwd) =>
+    runGitStdout("GitCore.listLocalBranchNames", cwd, [
+      "branch",
+      "--list",
+      "--format=%(refname:short)",
+    ]).pipe(
+      Effect.map((stdout) =>
+        stdout
+          .split("\n")
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0),
+      ),
+    );
+
   return {
     status,
     statusDetails,
@@ -1188,6 +1202,7 @@ const makeGitCore = Effect.gen(function* () {
     createBranch,
     checkoutBranch,
     initRepo,
+    listLocalBranchNames,
   } satisfies GitCoreShape;
 });