@10et/cli 1.0.0

package/packages/pi/extensions/index.ts

@@ -0,0 +1,601 @@
+/**
+ * JFL Pi Extension — Master Entry (Factory Function)
+ *
+ * Pi loads this as a factory: export default async function(pi: ExtensionAPI).
+ * We construct a PiContext shim exposing full Pi TUI capabilities to all
+ * JFL sub-extensions: overlays, custom footer, shortcuts, tool rendering,
+ * interactive dialogs, notifications, state persistence, and more.
+ *
+ * @purpose Master entry point for @tenet-ai/pi — full TUI-powered extension
+ */
+
+import { readFileSync, existsSync } from "fs"
+import { join } from "path"
+import { execSync } from "child_process"
+import type { PiContext, JflConfig, JflToolDef, JflCommandDef, PiTheme } from "./types.js"
+import { setupSession, onShutdown, getSessionBranch } from "./session.js"
+import { setupContext, injectContext } from "./context.js"
+import { setupJournal, checkJournalBeforeCompact, onJournalAgentEnd, onToolExecutionEnd, checkPurposeHeader, hasJournalEntryForSession } from "./journal.js"
+import { setupMapBridge, onMapBridgeShutdown, onMapToolEnd } from "./map-bridge.js"
+import { setupEval, onAgentEnd as onEvalEnd } from "./eval.js"
+import { setupHudTool, updateHudWidget, getHudForSteer } from "./hud-tool.js"
+import { setupCrmTool } from "./crm-tool.js"
+import { setupMemoryTool } from "./memory-tool.js"
+import { setupSynopsisTool } from "./synopsis-tool.js"
+import { setupPivotTool } from "./pivot-tool.js"
+import { initStratusBridge, onAgentStart as onStratusStart, onAgentEnd as onStratusEnd } from "./stratus-bridge.js"
+import { setupPeterParker } from "./peter-parker.js"
+import { setupPortfolioBridge, onPortfolioShutdown } from "./portfolio-bridge.js"
+import { setupAgentGrid } from "./agent-grid.js"
+import { initAgentNames } from "./agent-names.js"
+import { setupEvalTool } from "./eval-tool.js"
+import { setupPolicyHeadTool } from "./policy-head-tool.js"
+import { setupTrainingBufferTool, onTrainingAgentEnd } from "./training-buffer-tool.js"
+import { setupAutoresearch } from "./autoresearch.js"
+import { setupServiceSkills } from "./service-skills.js"
+import { setupHubTools } from "./hub-tools.js"
+import { setupFooter } from "./footer.js"
+import { setupShortcuts } from "./shortcuts.js"
+import { setupNotifications } from "./notifications.js"
+import { setupBookmarks } from "./bookmarks.js"
+import { setupSubwayMesh, injectMeshContext, onMeshShutdown } from "./subway-mesh.js"
+import { fireStartupBriefing } from "./startup-briefing.js"
+import { setupHeader, setHeaderHubStatus, setHeaderAutoCommit, setHeaderBranch, refreshHeaderData } from "./header.js"
+import { setupOnboarding as setupOnboardingV1 } from "./onboarding-v1.js"
+import { setupOnboarding as setupOnboardingV2 } from "./onboarding-v2.js"
+import { setupOnboarding as setupOnboardingV3 } from "./onboarding-v3.js"
+
+function selectOnboarding(config: JflConfig): (ctx: PiContext, config: JflConfig) => Promise<void> {
+  const variant = process.env.JFL_ONBOARDING_VARIANT ?? config.pi?.onboarding_variant ?? "v2"
+  switch (variant) {
+    case "v1": return setupOnboardingV1
+    case "v3": return setupOnboardingV3
+    case "v2":
+    default: return setupOnboardingV2
+  }
+}
+
+function readJflConfig(projectRoot: string): JflConfig {
+  // Check .tenet/ first, fall back to .jfl/ for backward compatibility
+  const tenetPath = join(projectRoot, ".tenet", "config.json")
+  const jflPath = join(projectRoot, ".jfl", "config.json")
+  const configPath = existsSync(tenetPath) ? tenetPath : jflPath
+  if (!existsSync(configPath)) return {}
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8")) as JflConfig
+  } catch {
+    return {}
+  }
+}
+
+function getProjectName(projectRoot: string, config: JflConfig): string {
+  if (config.name) return config.name
+  const visionPath = join(projectRoot, "knowledge", "VISION.md")
+  if (existsSync(visionPath)) {
+    const content = readFileSync(visionPath, "utf-8")
+    const match = content.match(/^#\s+(.+)/m)
+    if (match) return match[1].trim()
+  }
+  return projectRoot.split("/").pop() ?? "JFL Project"
+}
+
+function getCurrentBranch(root: string): string {
+  try {
+    return execSync("git branch --show-current", { cwd: root, stdio: ["pipe", "pipe", "ignore"] })
+      .toString().trim() || "main"
+  } catch {
+    return "main"
+  }
+}
+
+// ─── Dedup guard ─────────────────────────────────────────────────────────────
+// When developing jfl-cli locally, Pi discovers the extension from BOTH the
+// local packages/pi/ AND the global npm-installed jfl package. Both run as
+// separate factory calls in the same process. This guard ensures only the
+// first one initializes — which is the local dev version (Pi loads project-
+// local extensions before global packages).
+
+const JFL_LOADED = Symbol.for("tenet-pi-extension-loaded")
+
+// ─── Pi TUI compatibility layer ──────────────────────────────────────────────
+// Pi 0.62.0+ requires renderCall/renderResult to return Component instances
+// (new Text(...)). We dynamically import pi-tui at runtime and wrap our
+// string-based renderers. If the import fails (older Pi, different install),
+// renderers are disabled and Pi uses its default fallback rendering.
+
+let PiText: (new (text: string, px: number, py: number) => any) | null = null
+
+async function loadPiTui(): Promise<void> {
+  try {
+    // pi-tui lives inside Pi's own node_modules, not ours.
+    // We run inside Pi's process but our file location is in jfl's package tree,
+    // so normal import() can't resolve it. Use createRequire from Pi's location.
+    const { createRequire } = await import("module")
+    const { execSync } = await import("child_process")
+    const piPath = execSync("which pi", { encoding: "utf-8" }).trim()
+    // Follow symlink to real path (e.g. npm global → dist/cli.js)
+    const { realpathSync } = await import("fs")
+    const realPi = realpathSync(piPath)
+    const piRequire = createRequire(realPi)
+    const tuiPath = piRequire.resolve("@mariozechner/pi-tui")
+    const tui = await import(tuiPath)
+    PiText = tui.Text
+  } catch {
+    // pi-tui not resolvable — disable custom renderers, Pi uses fallback
+    PiText = null
+  }
+}
+
+/**
+ * Wrap a string-based renderer into a Pi Component.
+ * If pi-tui is available, returns new Text(). Otherwise returns undefined
+ * so Pi falls back to default rendering.
+ */
+function wrapRenderer(
+  fn: ((args: any, theme: any) => any) | undefined
+): ((args: any, theme: any, context: any) => any) | undefined {
+  if (!fn || !PiText) return undefined
+  return (args: any, theme: any, _context: any) => {
+    try {
+      const result = fn(args, theme)
+      // Old renderers return { render, invalidate }. Extract the lines.
+      if (result && typeof result.render === "function") {
+        const lines: string[] = result.render(140)
+        return new PiText!(lines.join("\n"), 0, 0)
+      }
+      return result
+    } catch {
+      return undefined
+    }
+  }
+}
+
+function wrapResultRenderer(
+  fn: ((result: any, opts: any, theme: any) => any) | undefined
+): ((result: any, opts: any, theme: any, context: any) => any) | undefined {
+  if (!fn || !PiText) return undefined
+  return (result: any, opts: any, theme: any, _context: any) => {
+    try {
+      const rendered = fn(result, opts, theme)
+      if (rendered && typeof rendered.render === "function") {
+        const lines: string[] = rendered.render(140)
+        return new PiText!(lines.join("\n"), 0, 0)
+      }
+      return rendered
+    } catch {
+      return undefined
+    }
+  }
+}
+
+// ─── Pi extension factory function ───────────────────────────────────────────
+
+export default async function jflExtension(pi: any): Promise<void> {
+  // Skip if already loaded from another source (dedup)
+  if ((globalThis as any)[JFL_LOADED]) {
+    return
+  }
+  (globalThis as any)[JFL_LOADED] = true
+
+  // Load Pi TUI for renderer compatibility — non-blocking, non-fatal
+  await loadPiTui()
+
+  let projectCwd = process.cwd()
+  let latestPiCtx: any = null
+
+  const internalHandlers = new Map<string, Array<(data: unknown) => void | Promise<void>>>()
+
+  function jflOn(event: string, handler: (data: unknown) => void | Promise<void>): void {
+    const list = internalHandlers.get(event) ?? []
+    list.push(handler)
+    internalHandlers.set(event, list)
+  }
+
+  function jflEmit(event: string, data?: unknown): void {
+    const list = internalHandlers.get(event) ?? []
+    list.forEach(h => Promise.resolve(h(data)).catch(() => {}))
+  }
+
+  // ─── Theme helper ───────────────────────────────────────────────────────────
+
+  function getTheme(): PiTheme {
+    if (latestPiCtx?.ui?.theme) return latestPiCtx.ui.theme
+    return {
+      fg: (_color: string, text: string) => text,
+      bg: (_color: string, text: string) => text,
+      bold: (text: string) => text,
+    }
+  }
+
+  // ─── PiContext shim — full TUI capabilities ─────────────────────────────────
+
+  const ctx: PiContext = {
+    get session() {
+      return {
+        projectRoot: projectCwd,
+        id: pi.getSessionName?.() ?? "jfl",
+        branch: getSessionBranch() || getCurrentBranch(projectCwd),
+      }
+    },
+
+    log: (msg: string, level?: string) => {
+      // Only show debug messages if JFL_DEBUG is set
+      if (level === "debug" && !process.env.JFL_DEBUG) return
+      const prefix = level === "debug" ? "[JFL debug]" : "[JFL]"
+      console.log(`${prefix} ${msg}`)
+    },
+
+    emit: jflEmit,
+    on: jflOn,
+
+    registerTool: (tool: JflToolDef) => {
+      pi.registerTool({
+        name: tool.name,
+        label: tool.label ?? tool.name,
+        description: tool.description,
+        promptSnippet: tool.promptSnippet,
+        promptGuidelines: tool.promptGuidelines,
+        parameters: tool.inputSchema,
+        async execute(_id: string, params: Record<string, unknown>) {
+          try {
+            const result = await tool.handler(params)
+            return {
+              content: [{ type: "text", text: result }],
+              details: { raw: result, toolName: tool.name },
+            }
+          } catch (err) {
+            throw new Error(`${err}`)
+          }
+        },
+        renderCall: wrapRenderer(tool.renderCall),
+        renderResult: wrapResultRenderer(tool.renderResult),
+      })
+    },
+
+    registerCommand: (cmd: JflCommandDef) => {
+      pi.registerCommand(cmd.name, {
+        description: cmd.description,
+        handler: async (args: string, piCtx: any) => {
+          latestPiCtx = piCtx
+          await cmd.handler(args, ctx)
+        },
+      })
+    },
+
+    registerShortcut: (key: string, opts: { description: string; handler: () => Promise<void> | void }) => {
+      pi.registerShortcut(key, {
+        description: opts.description,
+        handler: async (piCtx: any) => {
+          latestPiCtx = piCtx
+          await opts.handler()
+        },
+      })
+    },
+
+    ui: {
+      notify: (msg: string, opts?: { level?: string }) => {
+        const type = opts?.level ?? "info"
+        if (latestPiCtx?.ui?.notify) {
+          latestPiCtx.ui.notify(msg, type)
+        } else {
+          console.log(`[JFL ${type}] ${msg}`)
+        }
+      },
+
+      input: async (title: string, placeholder?: string) => {
+        if (latestPiCtx?.ui?.input) return latestPiCtx.ui.input(title, placeholder)
+        return undefined
+      },
+
+      confirm: async (title: string, message: string) => {
+        if (latestPiCtx?.ui?.confirm) return latestPiCtx.ui.confirm(title, message)
+        return false
+      },
+
+      select: async <T extends string>(title: string, items: Array<{ value: T; label: string; description?: string }>) => {
+        if (latestPiCtx?.ui?.select) return latestPiCtx.ui.select(title, items)
+        return null
+      },
+
+      editor: async (title: string, content: string) => {
+        if (latestPiCtx?.ui?.editor) return latestPiCtx.ui.editor(title, content)
+        return undefined
+      },
+
+      custom: async <T>(factory: any, opts?: any) => {
+        if (latestPiCtx?.ui?.custom) return latestPiCtx.ui.custom(factory, opts)
+        return undefined as T
+      },
+
+      setWidget: (id: string, content: any, opts?: { placement?: string }) => {
+        if (!latestPiCtx?.ui?.setWidget) return
+        if (content === undefined) {
+          latestPiCtx.ui.setWidget(id, undefined)
+        } else if (typeof content === "function") {
+          latestPiCtx.ui.setWidget(id, content, opts)
+        } else {
+          latestPiCtx.ui.setWidget(id, content, opts)
+        }
+      },
+
+      setStatus: (key: string, text: string | undefined) => {
+        if (latestPiCtx?.ui?.setStatus) latestPiCtx.ui.setStatus(key, text)
+      },
+
+      setFooter: (factory: any) => {
+        if (latestPiCtx?.ui?.setFooter) latestPiCtx.ui.setFooter(factory)
+      },
+
+      setHeader: (factory: any) => {
+        if (latestPiCtx?.ui?.setHeader) latestPiCtx.ui.setHeader(factory)
+      },
+
+      setEditorText: (text: string) => {
+        if (latestPiCtx?.ui?.setEditorText) latestPiCtx.ui.setEditorText(text)
+      },
+
+      get theme(): PiTheme {
+        return getTheme()
+      },
+
+      get hasUI(): boolean {
+        return latestPiCtx?.hasUI ?? false
+      },
+    },
+
+    pi: {
+      setSessionName: (name: string) => pi.setSessionName(name),
+
+      appendEntry: (type: string, data?: unknown) => {
+        if (pi.appendEntry) pi.appendEntry(type, data)
+      },
+
+      setLabel: (entryId: string, label: string | undefined) => {
+        if (pi.setLabel) pi.setLabel(entryId, label)
+      },
+
+      sendMessage: (msg: any, opts?: any) => {
+        if (pi.sendMessage) pi.sendMessage(msg, opts)
+      },
+
+      events: {
+        on: (event: string, handler: (data: unknown) => void) => {
+          if (pi.events?.on) pi.events.on(event, handler)
+        },
+        emit: (event: string, data?: unknown) => {
+          if (pi.events?.emit) pi.events.emit(event, data)
+        },
+      },
+
+      getActiveTools: () => pi.getActiveTools?.() ?? [],
+      getAllTools: () => pi.getAllTools?.() ?? [],
+
+      exec: async (command: string, args: string[], opts?: any) => {
+        if (pi.exec) return pi.exec(command, args, opts)
+        return { stdout: "", stderr: "exec unavailable", code: 1 }
+      },
+
+      get sessionManager() { return latestPiCtx?.sessionManager },
+      get model() { return latestPiCtx?.model },
+    },
+
+    cancel: () => ({ cancel: true as const }),
+  }
+
+  // ─── Session tracking state ────────────────────────────────────────────────
+
+  let turnCount = 0
+  let sessionStartTime = Date.now()
+  let currentModel = ""
+
+  // ─── Lifecycle handlers ────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event: unknown, piCtx: any) => {
+    latestPiCtx = piCtx
+    projectCwd = piCtx.cwd
+    turnCount = 0
+    sessionStartTime = Date.now()
+    currentModel = piCtx.model?.id ?? ""
+
+    const config = readJflConfig(projectCwd)
+    const projectName = getProjectName(projectCwd, config)
+
+    pi.setSessionName(`JFL: ${projectName}`)
+
+    // ─── Agent mode: minimal setup, no ceremony ──────────────────────
+    // PP agents and RL agents set JFL_AGENT_MODE=1. They need tools
+    // (memory, training buffer, hub) but NOT session branching, onboarding,
+    // header/footer/shortcuts, startup briefing, or any TUI elements.
+    // This cuts startup from 2+ minutes to <5 seconds.
+    const isAgentMode = process.env.JFL_AGENT_MODE === "1" || process.env.JFL_PP_SPAWNED === "1"
+
+    if (isAgentMode) {
+      // Agent mode: essential tools only, no ceremony
+      ctx.log("Agent mode — minimal setup (tools only, no ceremony)", "info")
+
+      await setupSession(ctx, config)       // Skips branching internally (detects agent mode)
+      setupMemoryTool(ctx)                   // Memory search — agents need project context
+      await setupTrainingBufferTool(ctx, config)  // Record training tuples from agent work
+      await setupEvalTool(ctx, config)       // Run evals to check improvement
+      await setupHubTools(ctx, config)       // Hub connection for tracking
+
+      ctx.log(`JFL Agent: ${projectName} — ready (${Date.now() - sessionStartTime}ms)`)
+      return
+    }
+
+    // ─── Interactive mode: full ceremony ──────────────────────────────
+
+    // Header first — replace Pi's default before anything renders
+    setupHeader(ctx, config)
+
+    // ─── Hub first, then animation + tools in parallel ─────────────
+    // Hub must be up before onboarding probes fire.
+    // setupContext starts hub + registers tenet_context tool.
+    await setupContext(ctx, config)
+
+    // Now hub is up — run animation + remaining setup in parallel
+    const doSetup = async () => {
+      await setupMapBridge(ctx, config)
+      await setupSession(ctx, config)
+      await setupJournal(ctx, config)
+      await setupEval(ctx, config)
+
+      setupHudTool(ctx)
+      setupCrmTool(ctx)
+      setupMemoryTool(ctx)
+      setupSynopsisTool(ctx)
+      setupPivotTool(ctx)
+      await setupEvalTool(ctx, config)
+      await setupPolicyHeadTool(ctx, config)
+      await setupTrainingBufferTool(ctx, config)
+      await setupAutoresearch(ctx, config)
+      await setupServiceSkills(ctx, config)
+      await setupHubTools(ctx, config)
+
+      await setupSubwayMesh(ctx, config)
+
+      initStratusBridge(projectCwd)
+      initAgentNames(projectCwd)
+      await setupPeterParker(ctx, config)
+      await setupPortfolioBridge(ctx, config)
+      setupAgentGrid(ctx)
+
+      setupFooter(ctx, config, { turnCount: () => turnCount, sessionStart: () => sessionStartTime, model: () => currentModel })
+      if (!config.pi?.disable_shortcuts) setupShortcuts(ctx, config)
+      if (!config.pi?.disable_notifications) setupNotifications(ctx, config)
+      setupBookmarks(ctx)
+    }
+
+    const onboard = config.pi?.disable_onboarding ? null : selectOnboarding(config)
+    await Promise.all([
+      onboard ? onboard(ctx, config).catch(() => {}) : Promise.resolve(),
+      doSetup(),
+    ])
+
+    ctx.log(`JFL: ${projectName} — session ready`)
+
+    // Fire startup briefing — gathers synopsis, PRs, team activity, next actions
+    // and steers the model to produce a concise "here's where things stand" greeting
+    if (config.pi?.auto_start !== false) {
+      await fireStartupBriefing(ctx, config)
+    }
+  })
+
+  pi.on("session_shutdown", async (_event: unknown, piCtx: any) => {
+    latestPiCtx = piCtx
+    try {
+      onMeshShutdown()
+      await onPortfolioShutdown(ctx)
+      await onShutdown(ctx)
+      await onMapBridgeShutdown(ctx)
+    } catch (err) {
+      ctx.log(`session_shutdown error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("session_before_compact", async (_event: unknown, piCtx: any) => {
+    latestPiCtx = piCtx
+    try {
+      return checkJournalBeforeCompact(ctx)
+    } catch (err) {
+      ctx.log(`session_before_compact error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("before_agent_start", async (event: any, _piCtx: any) => {
+    try {
+      const result = await injectContext(ctx, event)
+      const meshState = injectMeshContext()
+      const additions = [
+        result?.systemPromptAddition,
+        meshState,
+      ].filter(Boolean).join("\n\n")
+
+      if (additions) {
+        const current = (event.systemPrompt as string) ?? ""
+        return {
+          systemPrompt: current
+            ? `${current}\n\n${additions}`
+            : additions,
+        }
+      }
+    } catch (err) {
+      ctx.log(`before_agent_start error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("agent_start", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    try {
+      await onStratusStart(ctx, event)
+      jflEmit("agent:start", event)
+    } catch (err) {
+      ctx.log(`agent_start error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("agent_end", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    try {
+      await onStratusEnd(ctx, event)
+      await onEvalEnd(ctx, event)
+      await onTrainingAgentEnd(ctx, event)
+      await updateHudWidget(ctx)
+      await onJournalAgentEnd(ctx, event)
+      jflEmit("agent:end", event)
+    } catch (err) {
+      ctx.log(`agent_end error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("turn_start", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    turnCount++
+    jflEmit("turn:start", { ...event, turnCount })
+  })
+
+  pi.on("turn_end", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    jflEmit("turn:end", { ...event, turnCount })
+  })
+
+  // UserPromptSubmit equivalent — detect approval/done patterns in user input
+  pi.on("input", async (event: any, _piCtx: any) => {
+    try {
+      const text = (event.text ?? "").trim()
+      if (!text) return { action: "continue" }
+
+      const approvalPatterns = /\b(done|approved|ship it|looks good|lgtm|merge it|go ahead|good to go)\b/i
+      if (approvalPatterns.test(text)) {
+        const branch = getCurrentBranch(ctx.session.projectRoot)
+        const hasJournal = hasJournalEntryForSession(ctx.session.projectRoot, branch)
+        if (!hasJournal) {
+          return {
+            action: "transform",
+            text: `${event.text}\n\n[System: The user just approved/completed something. Write a journal entry NOW before proceeding — capture what was approved, decisions made, and next steps. Use the journal format from CLAUDE.md.]`,
+          }
+        }
+      }
+    } catch (err) {
+      ctx.log(`input handler error: ${err}`, "warn")
+    }
+    return { action: "continue" }
+  })
+
+  pi.on("tool_execution_end", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    try {
+      await onToolExecutionEnd(ctx, event)   // git commit → journal nudge
+      checkPurposeHeader(ctx, event)          // Write/Edit → @purpose check
+      await onMapToolEnd(ctx, event)          // hub event bus
+    } catch (err) {
+      ctx.log(`tool_execution_end error: ${err}`, "warn")
+    }
+  })
+
+  pi.on("model_select", async (event: any, piCtx: any) => {
+    latestPiCtx = piCtx
+    currentModel = event.model?.id ?? ""
+    jflEmit("model:changed", event)
+  })
+}

package/packages/pi/extensions/jfl-resolve.ts

@@ -0,0 +1,98 @@
+/**
+ * Resolve jfl-cli library modules at runtime.
+ *
+ * Extensions can't use relative imports like ../../src/lib/foo.js because
+ * the path only works when running from the jfl-cli source tree. When Pi
+ * loads us as a package, we need to find jfl's actual install location.
+ *
+ * Resolution order:
+ *   1. JFL_CLI_DIR env var (explicit override)
+ *   2. `which jfl` → follow symlink → dist/index.js → repo root
+ *   3. npm global: /opt/homebrew/lib/node_modules/jfl/
+ *   4. Fallback: ../../ (source tree — dev only)
+ *
+ * @purpose Resolve jfl-cli library paths for Pi extension imports
+ */
+
+import { existsSync, readlinkSync, realpathSync } from "fs"
+import { join, dirname, resolve } from "path"
+import { execSync } from "child_process"
+
+let jflRoot: string | null = null
+
+function findJflRoot(): string {
+  if (jflRoot) return jflRoot
+
+  // 1. Explicit env
+  if (process.env.JFL_CLI_DIR) {
+    const dir = process.env.JFL_CLI_DIR
+    if (existsSync(join(dir, "dist", "lib"))) {
+      jflRoot = dir
+      return dir
+    }
+  }
+
+  // 2. Follow `which jfl` symlink
+  try {
+    const jflBin = execSync("which jfl", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim()
+    if (jflBin) {
+      const realPath = realpathSync(jflBin)
+      // realPath is like /path/to/jfl-cli/dist/index.js
+      const distDir = dirname(realPath)
+      const root = dirname(distDir)
+      if (existsSync(join(root, "dist", "lib"))) {
+        jflRoot = root
+        return root
+      }
+    }
+  } catch {}
+
+  // 3. npm global locations
+  const npmGlobalPaths = [
+    "/opt/homebrew/lib/node_modules/jfl",
+    "/usr/local/lib/node_modules/jfl",
+  ]
+  for (const p of npmGlobalPaths) {
+    if (existsSync(join(p, "dist", "lib"))) {
+      jflRoot = p
+      return p
+    }
+  }
+
+  // 4. Fallback: source tree (dev only)
+  const devRoot = resolve(dirname(new URL(import.meta.url).pathname), "..", "..")
+  if (existsSync(join(devRoot, "dist", "lib"))) {
+    jflRoot = devRoot
+    return devRoot
+  }
+
+  // Last resort
+  jflRoot = devRoot
+  return devRoot
+}
+
+/**
+ * Import a jfl-cli library module by name.
+ *
+ * Usage:
+ *   const { PolicyHeadInference } = await jflImport("policy-head")
+ *   const { TrainingBuffer } = await jflImport("training-buffer")
+ *   const { phoneHomeToPortfolio } = await jflImport("service-gtm")
+ */
+export async function jflImport(moduleName: string): Promise<any> {
+  const root = findJflRoot()
+  const modulePath = join(root, "dist", "lib", `${moduleName}.js`)
+
+  if (!existsSync(modulePath)) {
+    throw new Error(`jfl module not found: ${moduleName} (looked in ${modulePath})`)
+  }
+
+  return import(modulePath)
+}
+
+/**
+ * Get the jfl-cli root directory.
+ */
+export function getJflRoot(): string {
+  return findJflRoot()
+}