Extract backlinks-index recipe CT-970 (commontoolsinc#1857)

* Extract `backlinks-index` recipe

* All wired up and almost working

* Use one index for all mentionables [CT-969]

* Compute global mentionable list and use it

* Format pass

Author: bfollington

packages/patterns/backlinks-index.tsx

@@ -0,0 +1,107 @@
+/// <cts-enable />
+import {
+  Cell,
+  cell,
+  Default,
+  derive,
+  lift,
+  NAME,
+  OpaqueRef,
+  recipe,
+  UI,
+} from "commontools";
+
+export type MentionableCharm = {
+  [NAME]: string;
+  content?: string;
+  mentioned?: MentionableCharm[];
+};
+
+type Input = {
+  allCharms: MentionableCharm[];
+};
+
+export type BacklinksMap = { [charmId: string]: MentionableCharm[] };
+
+type Output = {
+  backlinks: BacklinksMap;
+  mentionable: MentionableCharm[];
+};
+
+/**
+ * BacklinksIndex builds a map of backlinks across all charms and exposes a
+ * unified mentionable list for consumers like editors.
+ *
+ * Behavior:
+ * - Backlinks are computed by scanning each charm's `mentioned` list and
+ *   mapping mention target -> list of source charms.
+ * - Mentionable list is a union of:
+ *   - every charm in `allCharms`
+ *   - any items a charm exports via a `mentionable` property
+ *     (either an array of charms or a Cell of such an array)
+ *
+ * The backlinks map is keyed by a charm's `content` value (falling back to
+ * its `[NAME]`). This mirrors how existing note patterns identify notes when
+ * computing backlinks locally.
+ */
+const BacklinksIndex = recipe<Input, Output>(
+  "BacklinksIndex",
+  ({ allCharms }) => {
+    const computeIndex = lift<
+      { allCharms: MentionableCharm[] },
+      BacklinksMap
+    >(
+      ({ allCharms }) => {
+        const cs = allCharms ?? [];
+        const index: BacklinksMap = {};
+
+        for (const c of cs) {
+          const mentions = c.mentioned ?? [];
+          for (const m of mentions) {
+            const key = m?.content || m?.[NAME];
+            if (!key) continue;
+            if (!index[key]) index[key] = [];
+            index[key].push(c);
+          }
+        }
+
+        return index;
+      },
+    );
+
+    const backlinks: OpaqueRef<BacklinksMap> = computeIndex({ allCharms });
+
+    // Compute mentionable list from allCharms via lift, then mirror that into
+    // a real Cell for downstream consumers that expect a Cell.
+    const computeMentionable = lift<
+      { allCharms: any[] },
+      MentionableCharm[]
+    >(({ allCharms }) => {
+      const cs = allCharms ?? [];
+      const out: MentionableCharm[] = [];
+      for (const c of cs) {
+        out.push(c);
+        const exported = (c as unknown as {
+          mentionable?: MentionableCharm[] | { get?: () => MentionableCharm[] };
+        }).mentionable;
+        if (Array.isArray(exported)) {
+          for (const m of exported) if (m) out.push(m);
+        } else if (exported && typeof (exported as any).get === "function") {
+          const arr = (exported as { get: () => MentionableCharm[] }).get() ??
+            [];
+          for (const m of arr) if (m) out.push(m);
+        }
+      }
+      return out;
+    });
+
+    return {
+      [NAME]: "BacklinksIndex",
+      [UI]: undefined,
+      backlinks,
+      mentionable: computeMentionable({ allCharms }),
+    };
+  },
+);
+
+export default BacklinksIndex;

packages/patterns/chatbot-list-view.tsx

@@ -18,6 +18,7 @@ import {
 } from "commontools";
 
 import Chat from "./chatbot-note-composed.tsx";
+import BacklinksIndex, { BacklinksMap } from "./backlinks-index.tsx";
 import { ListItem } from "./common-tools.tsx";
 
 export type MentionableCharm = {
@@ -36,6 +37,7 @@ type Input = {
   selectedCharm: Default<{ charm: any }, { charm: undefined }>;
   charmsList: Default<CharmEntry[], []>;
   allCharms: Cell<any[]>;
+  index: BacklinksMap;
   theme?: {
     accentColor: Default<string, "#3b82f6">;
     fontFace: Default<string, "system-ui, -apple-system, sans-serif">;
@@ -45,6 +47,10 @@ type Input = {
 
 type Output = {
   selectedCharm: Default<{ charm: any }, { charm: undefined }>;
+  // Expose a mentionable list aggregated from local chat entries
+  // Returned as an opaque ref to an array (not a Cell), suitable for
+  // upstream aggregators that read exported mentionables.
+  mentionable?: MentionableCharm[];
 };
 
 const removeChat = handler<
@@ -89,7 +95,7 @@ const storeCharm = lift(
     charm: any;
     selectedCharm: Cell<Default<{ charm: any }, { charm: undefined }>>;
     charmsList: Cell<CharmEntry[]>;
-    allCharms: Cell<any[]>;
+    allCharms: Cell<MentionableCharm[]>;
     theme?: {
       accentColor: Default<string, "#3b82f6">;
       fontFace: Default<string, "system-ui, -apple-system, sans-serif">;
@@ -124,10 +130,11 @@ const populateChatList = lift(
     charmsList: CharmEntry[];
     allCharms: Cell<any[]>;
     selectedCharm: Cell<{ charm: any }>;
+    index: any;
   }>(),
   undefined,
   (
-    { charmsList, allCharms, selectedCharm },
+    { charmsList, allCharms, selectedCharm, index },
   ) => {
     if (charmsList.length === 0) {
       const isInitialized = cell(false);
@@ -137,6 +144,7 @@ const populateChatList = lift(
           messages: [],
           content: "",
           allCharms,
+          index,
         }),
         selectedCharm,
         charmsList,
@@ -155,16 +163,18 @@ const createChatRecipe = handler<
     selectedCharm: Cell<{ charm: any }>;
     charmsList: Cell<CharmEntry[]>;
     allCharms: Cell<any[]>;
+    index: any;
   }
 >(
-  (_, { selectedCharm, charmsList, allCharms }) => {
+  (_, { selectedCharm, charmsList, allCharms, index }) => {
     const isInitialized = cell(false);
 
     const charm = Chat({
       title: "New Chat",
       messages: [],
       content: "",
       allCharms,
+      index,
     });
     // store the charm ref in a cell (pass isInitialized to prevent recursive calls)
     return storeCharm({
@@ -234,24 +244,40 @@ const getCharmName = lift(({ charm }: { charm: any }) => {
 // create the named cell inside the recipe body, so we do it just once
 export default recipe<Input, Output>(
   "Launcher",
-  ({ selectedCharm, charmsList, allCharms, theme }) => {
+  ({ selectedCharm, charmsList, allCharms, index, theme }) => {
     logCharmsList({ charmsList: charmsList as unknown as Cell<CharmEntry[]> });
 
+    const combined = combineLists({
+      allCharms: allCharms as unknown as MentionableCharm[],
+      charmsList,
+    });
+
     populateChatList({
       selectedCharm: selectedCharm as unknown as Cell<
         Pick<CharmEntry, "charm">
       >,
       charmsList,
       allCharms,
-    });
-
-    const combined = combineLists({
-      allCharms: allCharms as unknown as any[],
-      charmsList,
+      index,
     });
 
     const selected = getSelectedCharm({ entry: selectedCharm });
 
+    // Aggregate mentionables from the local charms list so that this
+    // container exposes its child chat/note charms as mention targets.
+    const localMentionable = lift<
+      { list: CharmEntry[] },
+      MentionableCharm[]
+    >(({ list }) => {
+      const out: MentionableCharm[] = [];
+      for (const entry of list) {
+        const c = entry.charm;
+        out.push(c.note);
+        out.push(c.chat);
+      }
+      return out;
+    })({ list: charmsList });
+
     const localTheme = theme ?? {
       accentColor: cell("#3b82f6"),
       fontFace: cell("system-ui, -apple-system, sans-serif"),
@@ -272,6 +298,7 @@ export default recipe<Input, Output>(
                       selectedCharm,
                       charmsList,
                       allCharms: combined as unknown as any,
+                      index,
                     })}
                   >
                     Create New Chat
@@ -289,6 +316,7 @@ export default recipe<Input, Output>(
                   selectedCharm,
                   charmsList,
                   allCharms: combined as unknown as any,
+                  index,
                 })}
               />
             </div>
@@ -459,6 +487,8 @@ export default recipe<Input, Output>(
       ),
       selectedCharm,
       charmsList,
+      // Expose the aggregated mentionables for parent-level indexing.
+      mentionable: localMentionable,
     };
   },
 );

packages/patterns/chatbot-note-composed.tsx

@@ -27,6 +27,7 @@ import {
 
 import Chat from "./chatbot.tsx";
 import Note from "./note.tsx";
+import { type BacklinksMap } from "./backlinks-index.tsx";
 import Tools, {
   addListItem,
   calculator,
@@ -69,6 +70,7 @@ type ChatbotNoteInput = {
   messages: Default<Array<BuiltInLLMMessage>, []>;
   content: Default<string, "">;
   allCharms: Cell<MentionableCharm[]>;
+  index: { backlinks: BacklinksMap; mentionable: Cell<MentionableCharm[]> };
 };
 
 type ChatbotNoteResult = {
@@ -79,6 +81,8 @@ type ChatbotNoteResult = {
   note: any;
   chat: any;
   list: Default<ListItem[], []>;
+  // Optional: expose sub-charms as mentionable targets
+  mentionable?: MentionableCharm[];
 };
 
 const newNote = handler<
@@ -89,14 +93,14 @@ const newNote = handler<
     /** A cell to store the result message indicating success or error */
     result: Cell<string>;
   },
-  { allCharms: Cell<MentionableCharm[]> }
+  { allCharms: Cell<MentionableCharm[]>; index: any }
 >(
   (args, state) => {
     try {
       const n = Note({
         title: args.title,
         content: args.content || "",
-        allCharms: state.allCharms,
+        index: state.index,
       });
 
       args.result.set(
@@ -241,7 +245,7 @@ const navigateToNote = handler<
 
 export default recipe<ChatbotNoteInput, ChatbotNoteResult>(
   "Chatbot + Note",
-  ({ title, messages, content, allCharms }) => {
+  ({ title, messages, content, allCharms, index }) => {
     const list = cell<ListItem[]>([]);
 
     const tools = {
@@ -299,12 +303,13 @@ export default recipe<ChatbotNoteInput, ChatbotNoteResult>(
         description: "Create a new note instance",
         handler: newNote({
           allCharms: allCharms as unknown as OpaqueRef<MentionableCharm[]>,
+          index: index as unknown as OpaqueRef<any>,
         }),
       },
     };
 
     const chat = Chat({ messages, tools, mentionable: allCharms });
-    const note = Note({ title, content, allCharms });
+    const note = Note({ title, content, index });
 
     return {
       [NAME]: title,
@@ -315,6 +320,11 @@ export default recipe<ChatbotNoteInput, ChatbotNoteResult>(
       mentioned: note.mentioned,
       backlinks: note.backlinks,
       list,
+      // Expose both child charms for mention systems that scan charm exports.
+      mentionable: [
+        chat as unknown as MentionableCharm,
+        note as unknown as MentionableCharm,
+      ],
     };
   },
 );