Add support for search aliases on subgraphs (#8608)

## Summary

- add commands for setting search aliases and description when in
subgraph
- in future we can add these fields to the dialog when publishing a
subgraph
- map workflow extra metadata on save/load from from/to subgraph node to
allow access via `canvas.subgraph.extra`

## Changes

**What**: 
- new core commands for Comfy.Subgraph.SetSearchAliases &
Comfy.Subgraph.SetDescription to be called when in a subgraph context
- update Publish command to allow command metadata arg for name
- update test executeCommand to allow passing metadata arg

## Review Focus

- When saving a subgraph, the outer workflow "wrapper" is created at the
point of publishing. So unlike a normal workflow `extra` property that
is available at any point, for a subgraph this is not accessible.
To workaround this, the `extra` property that exists on the inner
subgraph node is copied to the top level on save, and restored on load
so extra properties can be set via `canvas.subgraph.extra`.
- I have kept the existing naming format matching `BlueprintDescription`
for `BlueprintSearchAliases` but i'm not sure if the description was
ever used before

## Screenshots


https://github.com/user-attachments/assets/4d4df9c1-2281-4589-aa56-ab07cdecd353

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-8608-Add-support-for-search-aliases-on-subgraphs-2fd6d73d365081d083caebd6befcacdd)
by [Unito](https://www.unito.io)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Set subgraph search aliases (comma-separated) and descriptions;
aliases enable discovery by alternative names.
  * Publish subgraphs using a provided name.
* Node definitions now support search aliases so nodes can be found by
alternate names.
  * UI strings added for entering descriptions and search aliases.

* **Tests**
* Added end-to-end and unit tests covering aliases, descriptions, search
behavior, publishing, and persistence.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

src/stores/nodeDefStore.ts

@@ -77,6 +77,11 @@ export class ComfyNodeDefImpl
    * and input connectivity.
    */
   readonly price_badge?: PriceBadge
+  /**
+   * Alternative names for search. Useful for synonyms, abbreviations,
+   * or old names after renaming a node.
+   */
+  readonly search_aliases?: string[]
 
   // V2 fields
   readonly inputs: Record<string, InputSpecV2>

src/stores/subgraphStore.test.ts

@@ -167,4 +167,142 @@ describe('useSubgraphStore', () => {
     await mockFetch({ 'test.json': mockGraph })
     expect(store.isGlobalBlueprint('nonexistent')).toBe(false)
   })
+
+  describe('search_aliases support', () => {
+    it('should include search_aliases from workflow extra', async () => {
+      const mockGraphWithAliases = {
+        nodes: [{ type: '123' }],
+        definitions: {
+          subgraphs: [{ id: '123' }]
+        },
+        extra: {
+          BlueprintSearchAliases: ['alias1', 'alias2', 'my workflow']
+        }
+      }
+      await mockFetch({ 'test-with-aliases.json': mockGraphWithAliases })
+
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.test-with-aliases'
+      )
+      expect(nodeDef).toBeDefined()
+      expect(nodeDef?.search_aliases).toEqual([
+        'alias1',
+        'alias2',
+        'my workflow'
+      ])
+    })
+
+    it('should include search_aliases from global blueprint info', async () => {
+      await mockFetch(
+        {},
+        {
+          global_with_aliases: {
+            name: 'Global With Aliases',
+            info: {
+              node_pack: 'comfy_essentials',
+              search_aliases: ['global alias', 'test alias']
+            },
+            data: JSON.stringify(mockGraph)
+          }
+        }
+      )
+
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.global_with_aliases'
+      )
+      expect(nodeDef).toBeDefined()
+      expect(nodeDef?.search_aliases).toEqual(['global alias', 'test alias'])
+    })
+
+    it('should not have search_aliases if not provided', async () => {
+      await mockFetch({ 'test.json': mockGraph })
+
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.test'
+      )
+      expect(nodeDef).toBeDefined()
+      expect(nodeDef?.search_aliases).toBeUndefined()
+    })
+
+    it('should include description from workflow extra', async () => {
+      const mockGraphWithDescription = {
+        nodes: [{ type: '123' }],
+        definitions: {
+          subgraphs: [{ id: '123' }]
+        },
+        extra: {
+          BlueprintDescription: 'This is a test blueprint'
+        }
+      }
+      await mockFetch({
+        'test-with-description.json': mockGraphWithDescription
+      })
+
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.test-with-description'
+      )
+      expect(nodeDef).toBeDefined()
+      expect(nodeDef?.description).toBe('This is a test blueprint')
+    })
+
+    it('should not duplicate metadata in both workflow extra and subgraph extra when publishing', async () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      const graph = subgraphNode.graph!
+      graph.add(subgraphNode)
+
+      // Set metadata on the subgraph's extra (as the commands do)
+      subgraph.extra = {
+        BlueprintDescription: 'Test description',
+        BlueprintSearchAliases: ['alias1', 'alias2']
+      }
+
+      vi.mocked(comfyApp.canvas).selectedItems = new Set([subgraphNode])
+      vi.mocked(comfyApp.canvas)._serializeItems = vi.fn(() => {
+        const serializedSubgraph = {
+          ...subgraph.serialize(),
+          links: [],
+          groups: [],
+          version: 1
+        } as Partial<ExportedSubgraph> as ExportedSubgraph
+        return {
+          nodes: [subgraphNode.serialize()],
+          subgraphs: [serializedSubgraph]
+        }
+      })
+
+      let savedWorkflowData: Record<string, unknown> | null = null
+      vi.mocked(api.storeUserData).mockImplementation(async (_path, data) => {
+        savedWorkflowData = JSON.parse(data as string)
+        return {
+          status: 200,
+          json: () =>
+            Promise.resolve({
+              path: 'subgraphs/testname.json',
+              modified: Date.now(),
+              size: 2
+            })
+        } as Response
+      })
+
+      await mockFetch({ 'testname.json': mockGraph })
+      await store.publishSubgraph()
+
+      expect(savedWorkflowData).not.toBeNull()
+
+      // Metadata should be in top-level extra
+      expect(savedWorkflowData!.extra).toEqual({
+        BlueprintDescription: 'Test description',
+        BlueprintSearchAliases: ['alias1', 'alias2']
+      })
+
+      // Metadata should NOT be in subgraph's extra
+      const definitions = savedWorkflowData!.definitions as {
+        subgraphs: Array<{ extra?: Record<string, unknown> }>
+      }
+      const subgraphExtra = definitions.subgraphs[0]?.extra
+      expect(subgraphExtra?.BlueprintDescription).toBeUndefined()
+      expect(subgraphExtra?.BlueprintSearchAliases).toBeUndefined()
+    })
+  })
 })

src/stores/subgraphStore.ts

@@ -95,18 +95,46 @@ export const useSubgraphStore = defineStore('subgraph', () => {
         if (!(await confirmOverwrite(this.filename))) return this
         this.hasPromptedSave = true
       }
+      // Extract metadata from subgraph.extra to workflow.extra before saving
+      this.extractMetadataToWorkflowExtra()
       const ret = await super.save()
-      registerNodeDef(await this.load(), {
+      // Force reload to update initialState with saved metadata
+      registerNodeDef(await this.load({ force: true }), {
         category: 'Subgraph Blueprints/User'
       })
       return ret
     }
 
+    /**
+     * Moves all properties (except workflowRendererVersion) from subgraph.extra
+     * to workflow.extra, then removes from subgraph.extra to avoid duplication.
+     */
+    private extractMetadataToWorkflowExtra(): void {
+      if (!this.activeState) return
+      const subgraph = this.activeState.definitions?.subgraphs?.[0]
+      if (!subgraph?.extra) return
+
+      const sgExtra = subgraph.extra as Record<string, unknown>
+      const workflowExtra = (this.activeState.extra ??= {}) as Record<
+        string,
+        unknown
+      >
+
+      for (const key of Object.keys(sgExtra)) {
+        if (key === 'workflowRendererVersion') continue
+        workflowExtra[key] = sgExtra[key]
+        delete sgExtra[key]
+      }
+    }
+
     override async saveAs(path: string) {
       this.validateSubgraph()
       this.hasPromptedSave = true
+      // Extract metadata from subgraph.extra to workflow.extra before saving
+      this.extractMetadataToWorkflowExtra()
       const ret = await super.saveAs(path)
-      registerNodeDef(await this.load(), {
+      // Force reload to update initialState with saved metadata
+      registerNodeDef(await this.load({ force: true }), {
         category: 'Subgraph Blueprints/User'
       })
       return ret
@@ -125,6 +153,17 @@ export const useSubgraphStore = defineStore('subgraph', () => {
           'Loaded subgraph blueprint does not contain valid subgraph'
         )
       sg.name = st.nodes[0].title = this.filename
+
+      // Copy blueprint metadata from workflow extra to subgraph extra
+      // so it's available when editing via canvas.subgraph.extra
+      if (st.extra) {
+        const sgExtra = (sg.extra ??= {}) as Record<string, unknown>
+        for (const [key, value] of Object.entries(st.extra)) {
+          if (key === 'workflowRendererVersion') continue
+          sgExtra[key] = value
+        }
+      }
+
       return loaded
     }
     override async promptSave(): Promise<string | null> {
@@ -177,7 +216,8 @@ export const useSubgraphStore = defineStore('subgraph', () => {
           {
             python_module: v.info.node_pack,
             display_name: v.name,
-            category
+            category,
+            search_aliases: v.info.search_aliases
           },
           k
         )
@@ -223,9 +263,10 @@ export const useSubgraphStore = defineStore('subgraph', () => {
         [`${i.type}`, undefined] satisfies InputSpec
       ])
     )
-    let description = 'User generated subgraph blueprint'
-    if (workflow.initialState.extra?.BlueprintDescription)
-      description = `${workflow.initialState.extra.BlueprintDescription}`
+    const workflowExtra = workflow.initialState.extra
+    const description =
+      workflowExtra?.BlueprintDescription ?? 'User generated subgraph blueprint'
+    const search_aliases = workflowExtra?.BlueprintSearchAliases
     const nodedefv1: ComfyNodeDefV1 = {
       input: { required: inputs },
       output: subgraphNode.outputs.map((o) => `${o.type}`),
@@ -236,13 +277,14 @@ export const useSubgraphStore = defineStore('subgraph', () => {
       category: 'Subgraph Blueprints',
       output_node: false,
       python_module: 'blueprint',
+      search_aliases,
       ...overrides
     }
     const nodeDefImpl = new ComfyNodeDefImpl(nodedefv1)
     subgraphDefCache.value.set(name, nodeDefImpl)
     subgraphCache[name] = workflow
   }
-  async function publishSubgraph() {
+  async function publishSubgraph(providedName?: string) {
     const canvas = canvasStore.getCanvas()
     const subgraphNode = [...canvas.selectedItems][0]
     if (
@@ -257,22 +299,25 @@ export const useSubgraphStore = defineStore('subgraph', () => {
     if (nodes.length != 1) {
       throw new TypeError('Must have single SubgraphNode selected to publish')
     }
+
     //create minimal workflow
     const workflowData = {
       revision: 0,
       last_node_id: subgraphNode.id,
       last_link_id: 0,
       nodes,
-      links: [],
+      links: [] as never[],
       version: 0.4,
       definitions: { subgraphs }
     }
     //prompt name
-    const name = await useDialogService().prompt({
-      title: t('subgraphStore.saveBlueprint'),
-      message: t('subgraphStore.blueprintNamePrompt'),
-      defaultValue: subgraphNode.title
-    })
+    const name =
+      providedName ??
+      (await useDialogService().prompt({
+        title: t('subgraphStore.saveBlueprint'),
+        message: t('subgraphStore.blueprintNamePrompt'),
+        defaultValue: subgraphNode.title
+      }))
     if (!name) return
     if (subgraphDefCache.value.has(name) && !(await confirmOverwrite(name)))
       //User has chosen not to overwrite.