feat(api): add metadata support to update mutation

- Add metadata field to UpdateMutationPayload
- Add asOptionalMetadata validation function
- Pass --metadata flag to bd update command
- Enables storing custom data like templateId on issues

src/lib/mutations.ts

@@ -27,6 +27,7 @@ export interface UpdateMutationPayload extends MutationBasePayload {
   issueType?: string;
   assignee?: string;
   labels?: string[];
+  metadata?: Record<string, unknown>;
 }
 
 export interface CloseMutationPayload extends MutationBasePayload {
@@ -117,6 +118,16 @@ function asOptionalLabels(value: unknown): string[] | undefined {
   return labels.length ? labels : undefined;
 }
 
+function asOptionalMetadata(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new MutationValidationError('"metadata" must be a JSON object.');
+  }
+  return value as Record<string, unknown>;
+}
+
 function asOptionalStatus(value: unknown): MutationStatus | undefined {
   if (value === undefined || value === null) {
     return undefined;
@@ -167,6 +178,7 @@ export function validateMutationPayload(operation: MutationOperation, payload: u
       issueType: asOptionalString(data.issueType),
       assignee: asOptionalString(data.assignee),
       labels: asOptionalLabels(data.labels),
+      metadata: asOptionalMetadata(data.metadata),
     };
 
     if (
@@ -176,7 +188,8 @@ export function validateMutationPayload(operation: MutationOperation, payload: u
       mapped.priority === undefined &&
       !mapped.issueType &&
       !mapped.assignee &&
-      !mapped.labels
+      !mapped.labels &&
+      !mapped.metadata
     ) {
       throw new MutationValidationError('At least one update field is required.');
     }
@@ -246,6 +259,9 @@ export function buildBdMutationArgs(operation: MutationOperation, payload: Mutat
     pushOptionalArg(args, '-t', data.issueType);
     pushOptionalArg(args, '-a', data.assignee);
     pushOptionalLabels(args, data.labels);
+    if (data.metadata) {
+      args.push('--metadata', JSON.stringify(data.metadata));
+    }
     args.push('--json');
     return args;
   }
@@ -299,7 +315,6 @@ export async function executeMutation(
     };
   }
 
-  // Emit event to notify SSE clients of the change
   issuesEventBus.emit(payload.projectRoot, undefined, 'changed');
 
   return {