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
@@ -31,7 +31,9 @@ import { confirmDialog } from "@/utils/confirm-dialog";
 import {
  applyDraftToConfig,
  configToDraft,
+  METADATA_PROMPT_KEYS,
  type LifecycleOriginalKind,
+  type MetadataPromptKey,
  type ProjectConfigDraft,
  type ProjectScriptDraft,
 } from "@/utils/project-config-form";
@@ -42,6 +44,40 @@ const SCRIPT_SERVICE_TYPE = "service";

 const ICON_SIZE = 14;

+interface MetadataPromptField {
+  title: string;
+  placeholder: string;
+  sectionTestID: string;
+  inputTestID: string;
+}
+
+const METADATA_PROMPT_FIELDS: Record<MetadataPromptKey, MetadataPromptField> = {
+  agentTitle: {
+    title: "Agent title prompt",
+    placeholder: "Keep titles short and action-oriented.",
+    sectionTestID: "metadata-prompt-agent-title-section",
+    inputTestID: "metadata-prompt-agent-title-input",
+  },
+  branchName: {
+    title: "Branch name prompt",
+    placeholder: "Prefix branches with feat/ or fix/.",
+    sectionTestID: "metadata-prompt-branch-name-section",
+    inputTestID: "metadata-prompt-branch-name-input",
+  },
+  commitMessage: {
+    title: "Commit message prompt",
+    placeholder: "Use Conventional Commits.",
+    sectionTestID: "metadata-prompt-commit-message-section",
+    inputTestID: "metadata-prompt-commit-message-input",
+  },
+  pullRequest: {
+    title: "Pull request prompt",
+    placeholder: "Include risk notes and a test plan.",
+    sectionTestID: "metadata-prompt-pull-request-section",
+    inputTestID: "metadata-prompt-pull-request-input",
+  },
+};
+
 const NO_TARGET_MESSAGE = "We don't have an editable copy of this project on any connected host.";

 const HOST_SWITCHER_LABEL = "Switch host";
@@ -432,6 +468,15 @@ function ProjectConfigForm({
    [updateDraft],
  );

+  const handleMetadataPromptChange = useCallback(
+    (key: MetadataPromptKey, text: string) =>
+      updateDraft((d) => ({
+        ...d,
+        metadataPrompts: { ...d.metadataPrompts, [key]: text },
+      })),
+    [updateDraft],
+  );
+
  const handleRemoveScript = useCallback(
    async (script: ProjectScriptDraft) => {
      const ok = await confirmDialog({
@@ -585,6 +630,15 @@ function ProjectConfigForm({
        </View>
      </SettingsSection>

+      {METADATA_PROMPT_KEYS.map((key) => (
+        <MetadataPromptSection
+          key={key}
+          promptKey={key}
+          value={draft.metadataPrompts[key]}
+          onChange={handleMetadataPromptChange}
+        />
+      ))}
+
      {isStale ? (
        <View style={styles.calloutWrap}>
          <Alert
@@ -767,6 +821,36 @@ function HostPickerItem({ host, isSelected, onSelectHost }: HostPickerItemProps)
  );
 }

+interface MetadataPromptSectionProps {
+  promptKey: MetadataPromptKey;
+  value: string;
+  onChange: (key: MetadataPromptKey, text: string) => void;
+}
+
+function MetadataPromptSection({ promptKey, value, onChange }: MetadataPromptSectionProps) {
+  const meta = METADATA_PROMPT_FIELDS[promptKey];
+  const handleChange = useCallback(
+    (text: string) => onChange(promptKey, text),
+    [onChange, promptKey],
+  );
+  return (
+    <SettingsSection title={meta.title} testID={meta.sectionTestID}>
+      <View style={settingsStyles.card}>
+        <TextInput
+          testID={meta.inputTestID}
+          accessibilityLabel={meta.title}
+          multiline
+          value={value}
+          onChangeText={handleChange}
+          placeholder={meta.placeholder}
+          placeholderTextColor={styles.placeholderColor.color}
+          style={styles.lifecycleInput}
+        />
+      </View>
+    </SettingsSection>
+  );
+}
+
 interface ScriptRowProps {
  script: ProjectScriptDraft;
  isFirst: boolean;
@@ -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;
 }