@asobacloud/nehanda 0.7.0 → 0.9.0

package/lib/explore.mjs

@@ -0,0 +1,109 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Directories to skip entirely during exploration
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.issues', 'dist', 'build', 'tmp', '.tmp',
+  'coverage', '.nyc_output', '__pycache__', '.venv', 'venv',
+  '.next', '.nuxt', 'out',
+])
+
+// Documentation files receive highest priority (read first)
+const DOC_FILENAMES = new Set([
+  'README.md', 'readme.md', 'README', 'readme',
+  'CONTRIBUTING.md', 'CONTRIBUTING', 'ARCHITECTURE.md', 'ARCHITECTURE',
+  'AGENTS.md', 'GEMINI.md', 'CHANGELOG.md', 'CHANGES.md',
+  'DESIGN.md', 'OVERVIEW.md', 'ONBOARDING.md', 'SETUP.md',
+  'MAP.md', 'RUNBOOK.md', 'OPERATIONS.md', 'SPECIFICATION.md', 'SPEC.md',
+])
+
+// Secondary documentation: anything under docs/ or .docs/
+const DOC_DIRS = new Set(['docs', '.docs', 'documentation', 'doc'])
+
+/**
+ * Scans a repository directory and returns files in documentation-first order.
+ *
+ * Priority order:
+ *   1. Root-level named documentation files (README.md, CONTRIBUTING.md, etc.)
+ *   2. All Markdown files inside docs/ subdirectories
+ *   3. Root-level *.md files not already listed
+ *   4. Configuration files (package.json, pyproject.toml, etc.)
+ *   5. All other source files (alphabetical, depth-first)
+ *
+ * @param {string} cwd - The repository root to scan
+ * @returns {string[]} - Absolute paths in exploration priority order
+ */
+export function getDocPrioritizedFiles(cwd) {
+  const abs = path.resolve(cwd)
+
+  // Tier 1: High-priority named root documentation files
+  const tier1 = []
+  for (const name of DOC_FILENAMES) {
+    const f = path.join(abs, name)
+    if (fs.existsSync(f) && fs.statSync(f).isFile()) {
+      tier1.push(f)
+    }
+  }
+
+  // Collect all files in the repo (excluding SKIP_DIRS)
+  const allFiles = []
+  function walk(dir) {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(path.join(dir, entry.name))
+      } else if (entry.isFile()) {
+        allFiles.push(path.join(dir, entry.name))
+      }
+    }
+  }
+  walk(abs)
+
+  const tier1Set = new Set(tier1)
+
+  // Tier 2: Markdown files inside docs/ directories
+  const tier2 = allFiles.filter(f => {
+    if (tier1Set.has(f)) return false
+    const rel = path.relative(abs, f)
+    const parts = rel.split(path.sep)
+    return parts.length > 1 && DOC_DIRS.has(parts[0]) && f.endsWith('.md')
+  })
+
+  const tier2Set = new Set(tier2)
+
+  // Tier 3: Remaining root-level *.md files
+  const tier3 = allFiles.filter(f => {
+    if (tier1Set.has(f) || tier2Set.has(f)) return false
+    const rel = path.relative(abs, f)
+    return !rel.includes(path.sep) && f.endsWith('.md')
+  })
+
+  const tier3Set = new Set(tier3)
+
+  // Tier 4: Config files
+  const CONFIG_NAMES = new Set([
+    'package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+    'pyproject.toml', 'setup.py', 'setup.cfg', 'Cargo.toml',
+    '.env.example', '.env.sample', 'tsconfig.json', 'jest.config.js',
+    'jest.config.mjs', 'eslint.config.js', '.eslintrc.js', '.eslintrc.json',
+  ])
+  const tier4 = allFiles.filter(f => {
+    if (tier1Set.has(f) || tier2Set.has(f) || tier3Set.has(f)) return false
+    const base = path.basename(f)
+    return CONFIG_NAMES.has(base)
+  })
+
+  const tier4Set = new Set(tier4)
+
+  // Tier 5: Everything else
+  const tier5 = allFiles.filter(f =>
+    !tier1Set.has(f) && !tier2Set.has(f) && !tier3Set.has(f) && !tier4Set.has(f)
+  )
+
+  return [...tier1, ...tier2, ...tier3, ...tier4, ...tier5]
+}

package/lib/issues.mjs

@@ -0,0 +1,144 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function slugify(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+}
+
+// ─── Core API ─────────────────────────────────────────────────────────────────
+
+/** Returns the /.issues/ directory path for the given repo root, creating it if needed. */
+export function getIssuesDir(cwd) {
+  const dir = path.join(cwd, '.issues')
+  fs.mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/** Returns the next consecutive issue number by scanning existing /.issues/ files. */
+export function getNextIssueNumber(cwd) {
+  const dir = getIssuesDir(cwd)
+  const files = fs.readdirSync(dir).filter(f => /^\d+/.test(f))
+  if (files.length === 0) return 1
+  const numbers = files.map(f => {
+    const m = f.match(/^(\d+)/)
+    return m ? parseInt(m[1], 10) : 0
+  })
+  return Math.max(...numbers) + 1
+}
+
+/**
+ * Creates a consecutively numbered structured markdown issue in /.issues/.
+ *
+ * @param {string} cwd - Repository root directory
+ * @param {object} opts
+ * @param {string} opts.title - Short issue title
+ * @param {string} opts.observed - Observed (broken) behavior
+ * @param {string} opts.expected - Expected (desired) behavior
+ * @param {string} opts.diagnosis - Evidence-backed root cause
+ * @param {string[]} opts.acceptanceCriteria - Array of AC strings (e.g. 'AC-1: ...', 'AC-2: ...')
+ * @returns {{ number: number, file: string, slug: string }}
+ */
+export function createIssue(cwd, { title, observed, expected, diagnosis, acceptanceCriteria = [] }) {
+  const num = getNextIssueNumber(cwd)
+  const numStr = String(num).padStart(4, '0')
+  const slug = slugify(title)
+  const filename = `${numStr}-${slug}.md`
+  const dir = getIssuesDir(cwd)
+  const file = path.join(dir, filename)
+
+  const acLines = acceptanceCriteria
+    .map(ac => `- [ ] ${ac}`)
+    .join('\n')
+
+  const created = new Date().toISOString()
+
+  const content = `# Issue #${numStr}: ${title}
+Status: open
+Created: ${created}
+
+## Observed Behavior
+${observed}
+
+## Expected Behavior
+${expected}
+
+## Evidenced Diagnosis
+${diagnosis}
+
+## Acceptance Criteria
+${acLines || '- [ ] AC-1: (define acceptance criteria)'}
+`
+
+  fs.writeFileSync(file, content, 'utf8')
+  return { number: num, file, slug }
+}
+
+/**
+ * Closes an open issue by updating its status and checking all AC checkboxes.
+ *
+ * @param {string} cwd - Repository root directory
+ * @param {number} issueNumber - The issue number to close
+ * @param {{ commitHash?: string }} [opts]
+ */
+export function closeIssue(cwd, issueNumber, opts = {}) {
+  const dir = getIssuesDir(cwd)
+  const numStr = String(issueNumber).padStart(4, '0')
+  const padded = new RegExp(`^0*${issueNumber}-.*\\.md$`)
+  const files = fs.readdirSync(dir).filter(f => padded.test(f) || f.startsWith(numStr + '-'))
+  if (files.length === 0) {
+    throw new Error(`Issue #${issueNumber} not found in ${dir}`)
+  }
+  const file = path.join(dir, files[0])
+  let content = fs.readFileSync(file, 'utf8')
+
+  // Update status
+  content = content.replace(/^Status: open$/m, 'Status: closed')
+
+  // Optionally record closed timestamp
+  if (opts.commitHash) {
+    content = content.replace(
+      /^Status: closed$/m,
+      `Status: closed\nClosed: ${new Date().toISOString()} (${opts.commitHash})`
+    )
+  }
+
+  // Check all unchecked boxes
+  content = content.replace(/^- \[ \]/gm, '- [x]')
+
+  fs.writeFileSync(file, content, 'utf8')
+  return { file, number: issueNumber }
+}
+
+/**
+ * Reads and returns metadata from an issue file.
+ *
+ * @param {string} cwd - Repository root directory
+ * @param {number} issueNumber
+ * @returns {{ number: number, file: string, status: string, title: string, content: string } | null}
+ */
+export function getIssue(cwd, issueNumber) {
+  const dir = getIssuesDir(cwd)
+  const numStr = String(issueNumber).padStart(4, '0')
+  const files = fs.readdirSync(dir).filter(f => f.startsWith(numStr + '-'))
+  if (files.length === 0) return null
+
+  const file = path.join(dir, files[0])
+  const content = fs.readFileSync(file, 'utf8')
+
+  const titleMatch = content.match(/^# Issue #\d+: (.+)$/m)
+  const statusMatch = content.match(/^Status: (\w+)$/m)
+
+  return {
+    number: issueNumber,
+    file,
+    title: titleMatch ? titleMatch[1] : '',
+    status: statusMatch ? statusMatch[1] : 'unknown',
+    content,
+  }
+}

package/lib/laya_sidecar.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const WORKER_PATH = path.resolve(__dirname, 'scripts', 'laya_worker.py')
 const ENSURE_SCRIPT = path.resolve(__dirname, 'scripts', 'ensure-laya-env.sh')
-const DEFAULT_TIMEOUT_MS = 100
+const DEFAULT_TIMEOUT_MS = Number(process.env.LAYA_TIMEOUT_MS) || 250
 const NEHANDA_HOME = process.env.NEHANDA_HOME || path.join(process.env.HOME || '/tmp', '.nehanda')
 const VENV_PYTHON = path.join(NEHANDA_HOME, 'venv', 'bin', 'python')
 const LAYA_READY_MARKER = path.join(NEHANDA_HOME, '.laya-ready')
@@ -135,12 +135,12 @@ export async function ensureLayaReady() {
     throw _provisionError
   }
 
-  // Warm the sidecar: spawn worker + send a real predict so the checkpoint
+  // Warm the sidecar: spawn worker + send a real load so the checkpoint
   // loads into memory before the first user turn.
   process.stderr.write('[laya-sidecar] warming Laya sidecar...\n')
-  const warm = await pingLaya(60_000)
-  if (!warm.ok) {
-    const msg = `[laya-sidecar] Laya warm-up failed: ${warm.error}`
+  const warm = await loadLaya(60_000)
+  if (!warm.ok || !warm.result?.loaded) {
+    const msg = `[laya-sidecar] Laya warm-up failed: ${warm.error || 'checkpoint load failed'}`
     process.stderr.write(msg + '\n')
     _provisionError = new Error(msg)
     throw _provisionError
@@ -177,6 +177,12 @@ export function layaRequest(method, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS)
   })
 }
 
+/** Warm load (loads checkpoint weights into memory/MPS). */
+export async function loadLaya(timeoutMs = 60_000) {
+  restartCount = 0
+  return layaRequest('load', {}, timeoutMs)
+}
+
 /** Warm ping (longer timeout for cold start). */
 export async function pingLaya(timeoutMs = 30_000) {
   restartCount = 0

package/lib/modelPicker.mjs

@@ -0,0 +1,124 @@
+/**
+ * Pure navigation logic for the /model wizard's large model picker (#10).
+ *
+ * Grouping, filtering, windowing (HP-2) and ask-prompt identity (HP-1a) live
+ * here as pure functions so they are directly testable. The React wiring is
+ * in bin/nehanda-ui.mjs (ModelPicker component / bridge.ask).
+ *
+ * HP-1a: every wizard question gets a unique ask id used as the React key for
+ *        AskPrompt, forcing a remount between questions so the typed value of
+ *        the previous question (e.g. an API key) can never carry into the
+ *        next prompt's input field.
+ * HP-2:  discovered lists longer than PICKER_THRESHOLD render in a picker with
+ *        vendor groups, type-to-filter search, and a centered window.
+ */
+
+/** Select lists longer than this switch to the grouped/filterable picker. */
+export const PICKER_THRESHOLD = 12
+
+/** Maximum rows rendered at once in browse/search views. */
+export const PICKER_WINDOW = 12
+
+/**
+ * Monotonic per-question id source for AskPrompt React keys (HP-1a).
+ * Distinct ids across consecutive questions ⇒ AskPrompt remounts ⇒ value
+ * state resets to '' for every new prompt.
+ */
+export function createAskIdSequencer() {
+  let n = 0
+  return {
+    next() { return ++n },
+  }
+}
+
+/**
+ * Vendor prefix of a discovered model id.
+ * OpenRouter style `vendor/model` → `vendor`; Ollama style `vendor:tag` →
+ * `vendor`; separator-less ids are their own single-model group.
+ * @param {string} name
+ */
+export function vendorOfModelId(name) {
+  const s = String(name ?? '')
+  const sep = s.includes('/') ? s.indexOf('/') : s.indexOf(':')
+  return sep === -1 ? s : s.slice(0, sep)
+}
+
+/**
+ * Group discovered model items by vendor (HP-2).
+ * Groups sort by size desc, then vendor name; the `__custom__` entry is
+ * always pinned last so it is reachable without scrolling.
+ * @param {{ id: string, name?: string, label?: string, desc?: string }[]} items
+ */
+export function groupModelsByVendor(items) {
+  const custom = items.find(i => i && i.id === '__custom__') || {
+    id: '__custom__',
+    label: '(enter custom name…)',
+    desc: 'Type a model id not listed above',
+  }
+  const real = items.filter(i => i && i.id !== '__custom__')
+  const byVendor = new Map()
+  for (const it of real) {
+    const vendor = vendorOfModelId(it.name ?? it.label ?? it.id ?? '')
+    if (!vendor) continue
+    if (!byVendor.has(vendor)) byVendor.set(vendor, [])
+    byVendor.get(vendor).push(it)
+  }
+  const groups = [...byVendor.entries()].map(([vendor, models]) => ({
+    id: vendor,
+    label: vendor,
+    desc: `${models.length} model${models.length === 1 ? '' : 's'}`,
+    models,
+    isCustom: false,
+  }))
+  groups.sort((a, b) => (b.models.length - a.models.length) || a.id.localeCompare(b.id))
+  groups.push({
+    id: '__custom__',
+    label: custom.label || '(enter custom name…)',
+    desc: 'Type a model id not listed above',
+    models: [custom],
+    isCustom: true,
+  })
+  return groups
+}
+
+/**
+ * Case-insensitive substring filter for type-to-search (HP-2).
+ * The `__custom__` entry is always pinned last, even with no matches, so the
+ * user can always fall back to typing a custom model id.
+ * @param {{ id: string, name?: string, label?: string }[]} items
+ * @param {string} query
+ */
+export function filterModelItems(items, query) {
+  const q = String(query ?? '').trim().toLowerCase()
+  const custom = items.find(i => i && i.id === '__custom__')
+  const real = items.filter(i => i && i.id !== '__custom__')
+  const matched = q
+    ? real.filter(i => String(i.name ?? i.label ?? '').toLowerCase().includes(q))
+    : real
+  return custom ? [...matched, custom] : matched
+}
+
+/**
+ * Centered window over a list for windowed rendering (HP-2).
+ * Keeps the cursor near the middle once the list overflows the window and
+ * reports hidden rows above/below for "…N more" hints.
+ * @param {any[]} list
+ * @param {number} cursor
+ * @param {number} [max] window size (default PICKER_WINDOW)
+ */
+export function visibleWindow(list, cursor, max = PICKER_WINDOW) {
+  const len = list.length
+  if (len <= max) {
+    return { start: 0, visible: list, hiddenAbove: 0, hiddenBelow: 0 }
+  }
+  const half = Math.floor(max / 2)
+  let start = cursor - half
+  if (start < 0) start = 0
+  if (start > len - max) start = len - max
+  return {
+    start,
+    visible: list.slice(start, start + max),
+    hiddenAbove: start,
+    hiddenBelow: len - (start + max),
+  }
+}

package/lib/openaiCompat.mjs

@@ -37,7 +37,7 @@ export function isAbortError(e) {
   return msg === 'Request was aborted.' || /operation was aborted/i.test(msg)
 }
 
-export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messages, tools, io, maxTokens = 8192, bufferOutput = true, num_ctx: numCtx, omitToolChoice: skipToolChoice = false, useStream = true, signal } = {}) {
+export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messages, tools, io, maxTokens = 8192, bufferOutput = true, num_ctx: numCtx, omitToolChoice: skipToolChoice = false, useStream = true, signal, think } = {}) {
   const url = `${String(baseUrl).replace(/\/$/, '')}/chat/completions`
   const body = { model, messages, stream: useStream, max_tokens: maxTokens }
   // Suppress tool_choice:"auto" for providers that do not support it (e.g. Nehanda
@@ -45,6 +45,8 @@ export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messa
   // send the tools schema so the model can call them — we just omit the directive.
   if (tools?.length) { body.tools = tools; if (!skipToolChoice) body.tool_choice = 'auto' }
   if (numCtx) body.num_ctx = numCtx
+  // #22: Ollama think:false disables chain-of-thought for models that support it
+  if (think === false) body.think = false
 
   const res = await fetch(url, {
     method: 'POST',
@@ -75,6 +77,10 @@ export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messa
       assistantBlocks,
       finishReason: json.choices?.[0]?.finish_reason || 'stop',
       bufferedText: bufferOutput ? strippedText : null,
+      // #11: preserve pre-strip content so an empty post-strip result stays
+      // diagnosable instead of being indistinguishable from "no response".
+      rawText: content,
+      rawLength: content?.length ?? 0,
       usage: json.usage || null,
     }
   }
@@ -82,6 +88,7 @@ export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messa
   const reader = res.body.getReader()
   const decoder = new TextDecoder()
   let buffer = '', fullText = '', finishReason = null, firstToken = true, usage = null
+  let reasoningTokenCount = 0  // #22: live reasoning token count for spinner updates
   const toolAcc = new Map()
 
   while (true) {
@@ -112,6 +119,15 @@ export async function streamOpenAIChatCompletion({ baseUrl, apiKey, model, messa
           io.write(delta.content)
         }
       }
+      // #22: reasoning tokens (Ollama delta.reasoning / delta.reasoning_content) —
+      // update spinner with live token count; never include in output text.
+      const reasoningChunk = delta?.reasoning ?? delta?.reasoning_content
+      if (reasoningChunk) {
+        reasoningTokenCount += reasoningChunk.split(/\s+/).filter(Boolean).length
+        if (io?.spinner?.update) {
+          io.spinner.update(`Thinking (${reasoningTokenCount} tokens)…`)
+        }
+      }
       if (delta?.tool_calls) {
         if (firstToken) {
           firstToken = false