conjure-js 0.0.12 → 0.0.13

package/src/bin/nrepl.ts

@@ -5,17 +5,24 @@ import { BDecoderStream, BEncoderStream } from './bencode'
 import {
   createSession,
   createSessionFromSnapshot,
+  cljNil,
   printString,
+  readString,
   snapshotSession,
-  type CljMap,
   type CljValue,
   type Session,
   type SessionSnapshot,
 } from '../core'
-import { tryLookup, lookupVar, getNamespaceEnv } from '../core/env'
+import { withPrintContext } from '../core/printer'
+import { derefValue } from '../core/env'
 import { inferSourceRoot } from './nrepl-utils'
+import {
+  resolveSymbol as resolveSymbolShared,
+  extractMeta as extractMetaShared,
+} from './nrepl-symbol'
 import { VERSION } from './version'
-import { injectNodeHostFunctions } from '../host/node'
+export { makeNodeHostModule } from '../host/node-host-module'
+import { makeNodeHostModule } from '../host/node-host-module'
 
 const CONJURE_VERSION = VERSION
 
@@ -25,6 +32,22 @@ const CONJURE_VERSION = VERSION
 
 type NreplMessage = Record<string, unknown>
 
+/** Streaming output chunk forwarded from a remote eval. */
+type RemoteStreamChunk =
+  | { type: 'out'; text: string }
+  | { type: 'err'; text: string }
+
+/** Minimal interface satisfied by MeshNode (structural — no import from the mesh experiment). */
+export type RemoteEvalNode = {
+  evalAt(
+    targetId: string,
+    source: string,
+    ns?: string,
+    timeoutMs?: number,
+    onChunk?: (chunk: RemoteStreamChunk) => void
+  ): Promise<{ value?: string; error?: string }>
+}
+
 type ManagedSession = {
   id: string
   session: Session
@@ -46,19 +69,23 @@ function createManagedSession(
   id: string,
   snapshot: SessionSnapshot,
   encoder: BEncoderStream,
-  sourceRoots?: string[]
+  sourceRoots?: string[],
+  onOutput?: (text: string) => void,
+  importModule?: (specifier: string) => unknown | Promise<unknown>
 ): ManagedSession {
   let currentMsgId = ''
 
   const session = createSessionFromSnapshot(snapshot, {
     output: (text) => {
       send(encoder, { id: currentMsgId, session: id, out: text })
+      onOutput?.(text)
     },
     readFile: (filePath) => readFileSync(filePath, 'utf8'),
     sourceRoots,
+    importModule,
   })
 
-  injectNodeHostFunctions(session)
+  session.runtime.installModules([makeNodeHostModule(session)])
 
   return {
     id,
@@ -105,11 +132,13 @@ function handleClone(
   sessions: Map<string, ManagedSession>,
   snapshot: SessionSnapshot,
   encoder: BEncoderStream,
-  sourceRoots?: string[]
+  sourceRoots?: string[],
+  onOutput?: (text: string) => void,
+  importModule?: (specifier: string) => unknown | Promise<unknown>
 ) {
   const id = (msg['id'] as string) ?? ''
   const newId = makeSessionId()
-  const managed = createManagedSession(newId, snapshot, encoder, sourceRoots)
+  const managed = createManagedSession(newId, snapshot, encoder, sourceRoots, onOutput, importModule)
   sessions.set(newId, managed)
   done(encoder, id, undefined, { 'new-session': newId })
 }
@@ -135,11 +164,12 @@ function handleDescribe(msg: NreplMessage, encoder: BEncoderStream) {
   })
 }
 
-function handleEval(
+async function handleEval(
   msg: NreplMessage,
   managed: ManagedSession,
-  encoder: BEncoderStream
-) {
+  encoder: BEncoderStream,
+  meshNode?: RemoteEvalNode
+): Promise<void> {
   const id = (msg['id'] as string) ?? ''
   const code = (msg['code'] as string) ?? ''
 
@@ -148,13 +178,134 @@ function handleEval(
   // Calva sends 1-based :line and :column for the start of the evaluated form
   // in the original file. Convert to 0-based offsets so evaluateDef can add
   // them to the relative positions the reader computes from the snippet.
-  const lineOffset = typeof msg['line']   === 'number' ? (msg['line']   as number) - 1 : 0
-  const colOffset  = typeof msg['column'] === 'number' ? (msg['column'] as number) - 1 : 0
+  const lineOffset =
+    typeof msg['line'] === 'number' ? (msg['line'] as number) - 1 : 0
+  const colOffset =
+    typeof msg['column'] === 'number' ? (msg['column'] as number) - 1 : 0
+
+  // Mesh routing: if mesh/*eval-target* is set and a meshNode is provided, route remotely.
+  // *eval-target* stores a CljString (set by set-target!) or CljNil (cleared).
+  //
+  // IMPORTANT: set-target! must ALWAYS run locally, regardless of the current target.
+  // If routed, (mesh/set-target! nil) would run on the remote node and clear ITS var,
+  // leaving the local target set — the user would be permanently stuck until reconnect.
+  //
+  // We detect "is this a set-target! call?" by resolving the head symbol in the local
+  // environment, not by regex. This correctly handles namespace aliases (:as m → m/set-target!),
+  // refers, and user renames — without any string matching on code.
+  // Vars that must always evaluate locally — reading or calling them on a
+  // remote node would return that node's state, not the local connection's.
+  const MESH_LOCAL_ONLY = new Set(['set-target!', '*eval-target*'])
+  const isMeshControl = (() => {
+    try {
+      const first = readString(code.trim())
+      // Direct symbol read: mesh/*eval-target*
+      if (first.kind === 'symbol') {
+        const resolved = resolveSymbol(first.name, managed)
+        return resolved?.resolvedNs === 'mesh' && MESH_LOCAL_ONLY.has(resolved.localName)
+      }
+      // Function call: (set-target! ...) or (mesh/set-target! ...)
+      if (first.kind !== 'list' || first.value.length === 0) return false
+      const head = first.value[0]
+      if (head.kind !== 'symbol') return false
+      const resolved = resolveSymbol(head.name, managed)
+      return resolved?.resolvedNs === 'mesh' && MESH_LOCAL_ONLY.has(resolved?.localName ?? '')
+    } catch {
+      return false
+    }
+  })()
+
+  if (!isMeshControl && meshNode) {
+    const meshNs = managed.session.getNs('mesh')
+    const evalTargetVar = meshNs?.vars.get('*eval-target*')
+    const targetVal = evalTargetVar?.value
+    if (targetVal?.kind === 'string' && targetVal.value) {
+      const targetId = targetVal.value
+      try {
+        const result = await meshNode.evalAt(
+          targetId,
+          code,
+          managed.session.currentNs,
+          undefined,
+          (chunk) => {
+            // Stream each chunk back to the editor immediately as it arrives —
+            // no buffering, works for million-line outputs and long-running evals.
+            if (chunk.type === 'out')
+              send(encoder, { id, session: managed.id, out: chunk.text })
+            else send(encoder, { id, session: managed.id, err: chunk.text })
+          }
+        )
+        if (result.error) {
+          done(encoder, id, managed.id, {
+            ex: result.error,
+            err: result.error + '\n',
+            ns: managed.session.currentNs,
+            status: ['eval-error', 'done'],
+          })
+        } else {
+          done(encoder, id, managed.id, {
+            value: result.value ?? 'nil',
+            ns: managed.session.currentNs,
+          })
+        }
+      } catch (e) {
+        const msg2 = e instanceof Error ? e.message : String(e)
+        const isUnreachable =
+          msg2.includes('not registered') || msg2.includes('Timeout')
+        if (isUnreachable) {
+          // Clear *eval-target* so the user isn't stuck on subsequent evals.
+          // Do NOT fall through to local eval — the code was intended for the
+          // remote node; running it locally could be dangerous or wrong.
+          const meshNsClear = managed.session.getNs('mesh')
+          const evalTargetVarClear = meshNsClear?.vars.get('*eval-target*')
+          if (evalTargetVarClear) evalTargetVarClear.value = cljNil()
+
+          const errMsg = `Node '${targetId}' unreachable — *eval-target* cleared. Eval dropped. Re-send to try on this node or try another node.\n`
+          done(encoder, id, managed.id, {
+            ex: errMsg,
+            err: errMsg,
+            ns: managed.session.currentNs,
+            status: ['eval-error', 'done'],
+          })
+        } else {
+          done(encoder, id, managed.id, {
+            ex: msg2,
+            err: msg2 + '\n',
+            ns: managed.session.currentNs,
+            status: ['eval-error', 'done'],
+          })
+        }
+      }
+      return
+    }
+  }
 
   try {
-    const result = managed.session.evaluate(code, { lineOffset, colOffset })
+    // evaluateAsync awaits any CljPending result before returning, so async
+    // forms, mesh/set-target!, mesh/list-nodes, etc. all resolve correctly
+    // before the nREPL response is sent. Sync evals are unaffected.
+    const result = await managed.session.evaluateAsync(code, {
+      lineOffset,
+      colOffset,
+    })
+    // Resolve *print-length* / *print-level* via the registry (same rationale
+    // as emitToOut in core-module.ts: session.getNs goes through the runtime
+    // registry so we always get the session's own freshly-cloned var, not a
+    // stale one from a snapshot closure env).
+    const coreNs = managed.session.getNs('clojure.core')
+    const lenVar = coreNs?.vars.get('*print-length*')
+    const lvlVar = coreNs?.vars.get('*print-level*')
+    const printLen = lenVar ? derefValue(lenVar) : undefined
+    const printLvl = lvlVar ? derefValue(lvlVar) : undefined
+    const resultStr = withPrintContext(
+      {
+        printLength: printLen?.kind === 'number' ? printLen.value : null,
+        printLevel: printLvl?.kind === 'number' ? printLvl.value : null,
+      },
+      () => printString(result)
+    )
     done(encoder, id, managed.id, {
-      value: printString(result),
+      value: resultStr,
       ns: managed.session.currentNs,
     })
   } catch (error) {
@@ -168,11 +319,11 @@ function handleEval(
   }
 }
 
-function handleLoadFile(
+async function handleLoadFile(
   msg: NreplMessage,
   managed: ManagedSession,
   encoder: BEncoderStream
-) {
+): Promise<void> {
   const id = (msg['id'] as string) ?? ''
   const source = (msg['file'] as string) ?? ''
   const fileName = (msg['file-name'] as string) ?? ''
@@ -193,7 +344,14 @@ function handleLoadFile(
 
     const nsHint =
       fileName.replace(/\.clj$/, '').replace(/\//g, '.') || undefined
-    const loadedNs = managed.session.loadFile(source, nsHint, filePath || undefined)
+
+    // loadFileAsync handles both sync and string (:require ["pkg" :as X]) forms.
+    // It falls back to the sync path internally if no async requires are present.
+    const loadedNs = await managed.session.loadFileAsync(
+      source,
+      nsHint,
+      filePath || undefined
+    )
 
     // Track the file path for this namespace so info/lookup can return :file
     // for go-to-definition support.
@@ -254,120 +412,15 @@ function resolveSymbol(
   sym: string,
   managed: ManagedSession,
   contextNs?: string
-): { value: CljValue; resolvedNs: string; localName: string } | null {
-  const ns = contextNs ?? managed.session.currentNs
-  const slashIdx = sym.indexOf('/')
-
-  if (slashIdx > 0) {
-    const qualifier = sym.slice(0, slashIdx)
-    const localName = sym.slice(slashIdx + 1)
-
-    // 1. Try as full namespace name (use registry Env for chain-based lookup)
-    const nsEnvFull = managed.session.registry.get(qualifier)
-    if (nsEnvFull) {
-      const value = tryLookup(localName, nsEnvFull)
-      if (value !== undefined) return { value, resolvedNs: qualifier, localName }
-    }
-
-    // 2. Try as alias (:as str → clojure.string)
-    const currentNsData = managed.session.getNs(ns)
-    const aliasedNs = currentNsData?.aliases.get(qualifier)
-    if (aliasedNs) {
-      const v = aliasedNs.vars.get(localName)
-      if (v !== undefined)
-        return { value: v.value, resolvedNs: aliasedNs.name, localName }
-    }
-
-    return null
-  }
-
-  // Unqualified symbol
-  const localName = sym
-  const nsEnvFull = managed.session.registry.get(ns)
-  if (!nsEnvFull) return null
-  const value = tryLookup(sym, nsEnvFull)
-  if (value === undefined) return null
-
-  // Determine the namespace where this symbol is defined.
-  // CljVar carries the authoritative ns; fall back to other heuristics.
-  const varObj = lookupVar(sym, nsEnvFull)
-  let resolvedNs: string
-  if (varObj) {
-    resolvedNs = varObj.ns
-  } else if (value.kind === 'function' || value.kind === 'macro') {
-    resolvedNs = getNamespaceEnv(value.env).ns?.name ?? ns
-  } else if (value.kind === 'native-function') {
-    const i = value.name.indexOf('/')
-    resolvedNs = i > 0 ? value.name.slice(0, i) : ns
-  } else {
-    resolvedNs = ns
-  }
-
-  return { value, resolvedNs, localName }
+) {
+  return resolveSymbolShared(sym, managed.session, contextNs)
 }
 
-function extractMeta(value: CljValue): {
-  doc: string
-  arglistsStr: string
-  eldocArgs: string[][] | null
-  type: string
-} {
-  const type =
-    value.kind === 'macro'
-      ? 'macro'
-      : value.kind === 'function' || value.kind === 'native-function'
-        ? 'function'
-        : 'var'
-
-  const meta: CljMap | undefined =
-    value.kind === 'function'
-      ? value.meta
-      : value.kind === 'native-function'
-        ? value.meta
-        : undefined
-
-  let doc = ''
-  let arglistsStr = ''
-  let eldocArgs: string[][] | null = null
-
-  if (meta) {
-    const docEntry = meta.entries.find(
-      ([k]) => k.kind === 'keyword' && k.name === ':doc'
-    )
-    if (docEntry && docEntry[1].kind === 'string') doc = docEntry[1].value
-
-    const argsEntry = meta.entries.find(
-      ([k]) => k.kind === 'keyword' && k.name === ':arglists'
-    )
-    if (argsEntry && argsEntry[1].kind === 'vector') {
-      const arglists = argsEntry[1]
-      arglistsStr = '(' + arglists.value.map((al) => printString(al)).join(' ') + ')'
-      eldocArgs = arglists.value.map((al) => {
-        if (al.kind !== 'vector') return [printString(al)]
-        return al.value.map((p) => (p.kind === 'symbol' ? p.name : printString(p)))
-      })
-    }
-  }
-
-  // Fallback: derive arglists from structural arities (fn/macro without meta)
-  if (
-    arglistsStr === '' &&
-    (value.kind === 'function' || value.kind === 'macro')
-  ) {
-    const arityStrs = value.arities.map((arity) => {
-      const params = arity.params.map((p) => printString(p))
-      if (arity.restParam) params.push('&', printString(arity.restParam))
-      return '[' + params.join(' ') + ']'
-    })
-    arglistsStr = '(' + arityStrs.join(' ') + ')'
-    eldocArgs = value.arities.map((arity) => {
-      const params = arity.params.map((p) => printString(p))
-      if (arity.restParam) params.push('&', printString(arity.restParam))
-      return params
-    })
-  }
-
-  return { doc, arglistsStr, eldocArgs, type }
+function extractMeta(resolved: {
+  value: CljValue
+  varObj?: import('./nrepl-symbol').ResolvedSymbol['varObj']
+}) {
+  return extractMetaShared(resolved.value, resolved.varObj?.meta)
 }
 
 function handleInfo(
@@ -401,20 +454,19 @@ function handleInfo(
     return
   }
 
-  const meta = extractMeta(resolved.value)
+  const meta = extractMeta(resolved)
   const file = managed.nsToFile.get(resolved.resolvedNs)
 
   // Extract :line/:column/:file from var meta if present (stamped by evaluateDef).
   let varLine: number | undefined
   let varColumn: number | undefined
   let varFile: string | undefined
-  if (resolved.value.kind === 'var' && resolved.value.meta) {
-    for (const [k, v] of resolved.value.meta.entries) {
-      if (k.kind !== 'keyword') continue
-      if (k.name === ':line'   && v.kind === 'number') varLine   = v.value
-      if (k.name === ':column' && v.kind === 'number') varColumn = v.value
-      if (k.name === ':file'   && v.kind === 'string') varFile   = v.value
-    }
+  const varMetaEntries = resolved.varObj?.meta?.entries ?? []
+  for (const [k, v] of varMetaEntries) {
+    if (k.kind !== 'keyword') continue
+    if (k.name === ':line' && v.kind === 'number') varLine = v.value
+    if (k.name === ':column' && v.kind === 'number') varColumn = v.value
+    if (k.name === ':file' && v.kind === 'string') varFile = v.value
   }
 
   done(encoder, id, managed.id, {
@@ -423,8 +475,8 @@ function handleInfo(
     doc: meta.doc,
     'arglists-str': meta.arglistsStr,
     type: meta.type,
-    ...(varFile ?? file ? { file: varFile ?? file } : {}),
-    ...(varLine   !== undefined ? { line: varLine }     : {}),
+    ...((varFile ?? file) ? { file: varFile ?? file } : {}),
+    ...(varLine !== undefined ? { line: varLine } : {}),
     ...(varColumn !== undefined ? { column: varColumn } : {}),
   })
 }
@@ -457,7 +509,7 @@ function handleEldoc(
     return
   }
 
-  const meta = extractMeta(resolved.value)
+  const meta = extractMeta(resolved)
   if (!meta.eldocArgs) {
     done(encoder, id, managed.id, { status: ['no-eldoc', 'done'] })
     return
@@ -486,7 +538,10 @@ function handleMessage(
   snapshot: SessionSnapshot,
   encoder: BEncoderStream,
   defaultSession: ManagedSession,
-  sourceRoots?: string[]
+  sourceRoots?: string[],
+  meshNode?: RemoteEvalNode,
+  onOutput?: (text: string) => void,
+  importModule?: (specifier: string) => unknown | Promise<unknown>
 ) {
   const op = msg['op'] as string
   const sessionId = msg['session'] as string | undefined
@@ -496,16 +551,32 @@ function handleMessage(
 
   switch (op) {
     case 'clone':
-      handleClone(msg, sessions, snapshot, encoder, sourceRoots)
+      handleClone(msg, sessions, snapshot, encoder, sourceRoots, onOutput, importModule)
       break
     case 'describe':
       handleDescribe(msg, encoder)
       break
     case 'eval':
-      handleEval(msg, managed, encoder)
+      void handleEval(msg, managed, encoder, meshNode).catch((e) => {
+        const m = e instanceof Error ? e.message : String(e)
+        done(encoder, (msg['id'] as string) ?? '', managed.id, {
+          ex: m,
+          err: m + '\n',
+          ns: managed.session.currentNs,
+          status: ['eval-error', 'done'],
+        })
+      })
       break
     case 'load-file':
-      handleLoadFile(msg, managed, encoder)
+      void handleLoadFile(msg, managed, encoder).catch((e) => {
+        const m = e instanceof Error ? e.message : String(e)
+        done(encoder, (msg['id'] as string) ?? '', managed.id, {
+          ex: m,
+          err: m + '\n',
+          ns: managed.session.currentNs,
+          status: ['eval-error', 'done'],
+        })
+      })
       break
     case 'complete':
       handleComplete(msg, managed, encoder)
@@ -535,6 +606,26 @@ export type NreplServerOptions = {
   port?: number
   host?: string
   sourceRoots?: string[]
+  /** Pre-created session (with modules already installed). Will be snapshotted internally. */
+  session?: Session
+  /** Or pass a pre-taken snapshot directly. Takes precedence over `session`. */
+  snapshot?: SessionSnapshot
+  /** Optional mesh node for routing eval ops when mesh/*eval-target* is set. */
+  meshNode?: RemoteEvalNode
+  /** Write .nrepl-port to cwd on listen. Default: true. Set false for embedded/server use. */
+  writePortFile?: boolean
+  /**
+   * Called for every stdout chunk from any managed session (i.e. local evals from the editor).
+   * Use this to echo output to the server terminal alongside the Calva encoder stream.
+   * Example: onOutput: (t) => process.stdout.write(t)
+   */
+  onOutput?: (text: string) => void
+  /**
+   * Called when (:require ["specifier" :as Alias]) is encountered in an eval.
+   * Forwarded to every managed session cloned from the snapshot.
+   * Example: importModule: (s) => import(s)
+   */
+  importModule?: (specifier: string) => unknown | Promise<unknown>
 }
 
 export function startNreplServer(options: NreplServerOptions = {}): net.Server {
@@ -542,12 +633,19 @@ export function startNreplServer(options: NreplServerOptions = {}): net.Server {
   const host = options.host ?? '127.0.0.1'
 
   // Build a warm snapshot once — all clones skip the core bootstrap.
-  // Source roots from config discovery are baked in so every cloned session inherits them.
-  const warmSession = createSession({
-    sourceRoots: options.sourceRoots,
-    readFile: (filePath) => readFileSync(filePath, 'utf8'),
-  })
-  const snapshot = snapshotSession(warmSession)
+  // Callers may provide a pre-created session (with extra modules installed) or snapshot.
+  const snapshot: SessionSnapshot =
+    options.snapshot ??
+    (options.session
+      ? snapshotSession(options.session)
+      : snapshotSession(
+          createSession({
+            sourceRoots: options.sourceRoots,
+            readFile: (filePath) => readFileSync(filePath, 'utf8'),
+          })
+        ))
+
+  const { meshNode, onOutput, importModule } = options
 
   const server = net.createServer((socket) => {
     const encoder = new BEncoderStream()
@@ -560,11 +658,28 @@ export function startNreplServer(options: NreplServerOptions = {}): net.Server {
 
     // A default session for session-less messages (e.g. Calva's initial eval)
     const defaultId = makeSessionId()
-    const defaultSession = createManagedSession(defaultId, snapshot, encoder, options.sourceRoots)
+    const defaultSession = createManagedSession(
+      defaultId,
+      snapshot,
+      encoder,
+      options.sourceRoots,
+      onOutput,
+      importModule
+    )
     sessions.set(defaultId, defaultSession)
 
     decoder.on('data', (msg: NreplMessage) => {
-      handleMessage(msg, sessions, snapshot, encoder, defaultSession, options.sourceRoots)
+      handleMessage(
+        msg,
+        sessions,
+        snapshot,
+        encoder,
+        defaultSession,
+        options.sourceRoots,
+        meshNode,
+        onOutput,
+        importModule
+      )
     })
 
     socket.on('error', () => {
@@ -577,25 +692,32 @@ export function startNreplServer(options: NreplServerOptions = {}): net.Server {
   })
 
   const portFile = join(process.cwd(), '.nrepl-port')
-
-  server.listen(port, host, () => {
-    writeFileSync(portFile, String(port), 'utf8')
-    process.stdout.write(`Conjure nREPL server v${VERSION} started on port ${port}\n`)
-  })
+  const writePortFile = options.writePortFile ?? true
 
   const cleanup = () => {
     if (existsSync(portFile)) unlinkSync(portFile)
   }
-  server.on('close', cleanup)
-  process.on('exit', cleanup)
-  process.on('SIGINT', () => {
-    cleanup()
-    process.exit(0)
-  })
-  process.on('SIGTERM', () => {
-    cleanup()
-    process.exit(0)
-  })
+
+  if (writePortFile) {
+    server.listen(port, host, () => {
+      writeFileSync(portFile, String(port), 'utf8')
+      process.stdout.write(
+        `Conjure nREPL server v${VERSION} started on port ${port}\n`
+      )
+    })
+    server.on('close', cleanup)
+    process.on('exit', cleanup)
+    process.on('SIGINT', () => {
+      cleanup()
+      process.exit(0)
+    })
+    process.on('SIGTERM', () => {
+      cleanup()
+      process.exit(0)
+    })
+  } else {
+    server.listen(port, host)
+  }
 
   return server
 }

package/src/bin/version.ts

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/gen-version.mjs
 // Do not edit manually - changes will be overwritten
 
-export const VERSION = '0.0.12'
+export const VERSION = '0.0.13'