feat: project-level prompts for metadata generation (#836)

* feat(server): project-level prompts for metadata generation Add `metadataGeneration` config to `paseo.json` so projects can customize the four LLM-generated metadata strings — agent title, worktree branch name, commit message, and pull request title+body. Each entry takes an `instructions` string that gets injected as a `<user-instructions>` block between the default rules and the load-bearing JSON format contract, with wrapper text saying user instructions override defaults. Missing/empty/invalid config keeps every prompt byte-identical to today. * refactor(server): centralize project metadata prompt building Three near-identical readers and four gate-then-wrap blocks collapsed into one buildMetadataPrompt helper. wrapWithUserInstructions tightened to require a non-empty string; its misleading empty fallback is gone. * feat(app): edit metadata generation prompts in project settings Adds four textareas (agent title, branch name, commit message, pull request) under project settings, modeled on the existing setup/teardown pattern. Round-trips through paseo.json preserving unknown sibling fields at both the metadataGeneration and entry level.
2026-05-09 18:36:29 +08:00
parent 8b09846f98
commit 030e163fb8
16 changed files with 1240 additions and 39 deletions
@@ -10,6 +10,13 @@ function emptyDraft(): ProjectConfigDraft {
    teardownText: "",
    teardownOriginalKind: "missing",
    scripts: [],
+    metadataPrompts: {
+      agentTitle: "",
+      branchName: "",
+      commitMessage: "",
+      pullRequest: "",
+    },
+    metadataGenerationBase: undefined,
  };
 }

@@ -210,6 +217,100 @@ describe("applyDraftToConfig", () => {
    expect(tunnel.port).toBe("auto");
  });

+  it("reads metadata prompt instructions for all four keys", () => {
+    const draft = configToDraft({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use mb/." },
+        branchName: { instructions: "feat/<slug>" },
+        commitMessage: { instructions: "Conventional commits." },
+        pullRequest: { instructions: "Include risk notes." },
+      },
+    });
+    expect(draft.metadataPrompts).toEqual({
+      agentTitle: "Use mb/.",
+      branchName: "feat/<slug>",
+      commitMessage: "Conventional commits.",
+      pullRequest: "Include risk notes.",
+    });
+  });
+
+  it("defaults metadata prompts to empty strings when not present", () => {
+    const draft = configToDraft({
+      metadataGeneration: { agentTitle: { instructions: "Use mb/." } },
+    });
+    expect(draft.metadataPrompts).toEqual({
+      agentTitle: "Use mb/.",
+      branchName: "",
+      commitMessage: "",
+      pullRequest: "",
+    });
+  });
+
+  it("writes only metadata prompt entries with non-empty text", () => {
+    const base: PaseoConfigRaw = {};
+    const draft = configToDraft(base);
+    draft.metadataPrompts.agentTitle = "Use mb/.";
+    draft.metadataPrompts.commitMessage = "Conventional commits.";
+    const next = applyDraftToConfig({ draft, base });
+    expect(next.metadataGeneration).toEqual({
+      agentTitle: { instructions: "Use mb/." },
+      commitMessage: { instructions: "Conventional commits." },
+    });
+  });
+
+  it("drops the metadataGeneration field when all prompts are empty", () => {
+    const base = PaseoConfigRawSchema.parse({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use mb/." },
+      },
+    });
+    const draft = configToDraft(base);
+    draft.metadataPrompts.agentTitle = "";
+    const next = applyDraftToConfig({ draft, base });
+    expect(next.metadataGeneration).toBeUndefined();
+  });
+
+  it("preserves unknown sibling fields inside metadataGeneration on round-trip", () => {
+    const base = PaseoConfigRawSchema.parse({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use mb/." },
+        futureField: 42,
+      },
+    });
+    const draft = configToDraft(base);
+    draft.metadataPrompts.agentTitle = "Use prefix mb/ on titles.";
+    const next = applyDraftToConfig({ draft, base });
+    const metadata = next.metadataGeneration as Record<string, unknown>;
+    expect(metadata.agentTitle).toEqual({ instructions: "Use prefix mb/ on titles." });
+    expect(metadata.futureField).toBe(42);
+  });
+
+  it("preserves unknown fields inside a metadata prompt entry on round-trip", () => {
+    const base = PaseoConfigRawSchema.parse({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use mb/.", model: "haiku" },
+      },
+    });
+    const draft = configToDraft(base);
+    draft.metadataPrompts.agentTitle = "Updated.";
+    const next = applyDraftToConfig({ draft, base });
+    const metadata = next.metadataGeneration as Record<string, unknown>;
+    expect(metadata.agentTitle).toEqual({ instructions: "Updated.", model: "haiku" });
+  });
+
+  it("clears instructions but preserves unknown sibling fields when text becomes empty", () => {
+    const base = PaseoConfigRawSchema.parse({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use mb/.", model: "haiku" },
+      },
+    });
+    const draft = configToDraft(base);
+    draft.metadataPrompts.agentTitle = "";
+    const next = applyDraftToConfig({ draft, base });
+    const metadata = next.metadataGeneration as Record<string, unknown>;
+    expect(metadata.agentTitle).toEqual({ model: "haiku" });
+  });
+
  it("drops scripts with an empty name and removes scripts no longer present in the draft", () => {
    const base = PaseoConfigRawSchema.parse({
      scripts: {
@@ -1,7 +1,20 @@
-import type { PaseoConfigRaw, PaseoScriptEntryRaw } from "@server/shared/messages";
+import type {
+  PaseoConfigRaw,
+  PaseoMetadataGeneration,
+  PaseoMetadataGenerationEntry,
+  PaseoScriptEntryRaw,
+} from "@server/shared/messages";

 export type LifecycleOriginalKind = "string" | "array" | "missing";

+export const METADATA_PROMPT_KEYS = [
+  "agentTitle",
+  "branchName",
+  "commitMessage",
+  "pullRequest",
+] as const;
+export type MetadataPromptKey = (typeof METADATA_PROMPT_KEYS)[number];
+
 export interface ProjectScriptDraft {
  id: string;
  name: string;
@@ -18,6 +31,8 @@ export interface ProjectConfigDraft {
  teardownText: string;
  teardownOriginalKind: LifecycleOriginalKind;
  scripts: ProjectScriptDraft[];
+  metadataPrompts: Record<MetadataPromptKey, string>;
+  metadataGenerationBase: PaseoMetadataGeneration | undefined;
 }

 interface LifecycleProjection {
@@ -88,6 +103,15 @@ function nextScriptDraftId(): string {
  return `script-draft-${scriptDraftIdCounter}`;
 }

+function emptyMetadataPrompts(): Record<MetadataPromptKey, string> {
+  return {
+    agentTitle: "",
+    branchName: "",
+    commitMessage: "",
+    pullRequest: "",
+  };
+}
+
 export function configToDraft(config: PaseoConfigRaw | null | undefined): ProjectConfigDraft {
  const worktree = config?.worktree ?? {};
  const setup = projectLifecycle(worktree.setup);
@@ -108,12 +132,23 @@ export function configToDraft(config: PaseoConfigRaw | null | undefined): Projec
    });
  }

+  const metadataGeneration = config?.metadataGeneration;
+  const metadataPrompts = emptyMetadataPrompts();
+  for (const key of METADATA_PROMPT_KEYS) {
+    const instructions = metadataGeneration?.[key]?.instructions;
+    if (typeof instructions === "string") {
+      metadataPrompts[key] = instructions;
+    }
+  }
+
  return {
    setupText: setup.text,
    setupOriginalKind: setup.kind,
    teardownText: teardown.text,
    teardownOriginalKind: teardown.kind,
    scripts,
+    metadataPrompts,
+    metadataGenerationBase: metadataGeneration,
  };
 }

@@ -172,6 +207,31 @@ export function applyDraftToConfig(input: ApplyDraftInput): PaseoConfigRaw {
    nextScripts[trimmedName] = nextEntry as PaseoScriptEntryRaw;
  }

+  const nextMetadataGeneration: Record<string, unknown> = {
+    ...input.draft.metadataGenerationBase,
+  };
+  for (const key of METADATA_PROMPT_KEYS) {
+    const text = input.draft.metadataPrompts[key];
+    const baseEntry = input.draft.metadataGenerationBase?.[key] as
+      | PaseoMetadataGenerationEntry
+      | undefined;
+    if (text.trim().length === 0) {
+      if (baseEntry) {
+        const nextEntry: Record<string, unknown> = { ...baseEntry };
+        delete nextEntry.instructions;
+        if (Object.keys(nextEntry).length === 0) {
+          delete nextMetadataGeneration[key];
+        } else {
+          nextMetadataGeneration[key] = nextEntry;
+        }
+      } else {
+        delete nextMetadataGeneration[key];
+      }
+    } else {
+      nextMetadataGeneration[key] = { ...baseEntry, instructions: text };
+    }
+  }
+
  const result: Record<string, unknown> = { ...baseConfig };
  if (Object.keys(nextWorktree).length === 0) {
    delete result.worktree;
@@ -183,5 +243,10 @@ export function applyDraftToConfig(input: ApplyDraftInput): PaseoConfigRaw {
  } else {
    result.scripts = nextScripts;
  }
+  if (Object.keys(nextMetadataGeneration).length === 0) {
+    delete result.metadataGeneration;
+  } else {
+    result.metadataGeneration = nextMetadataGeneration;
+  }
  return result as PaseoConfigRaw;
 }