fdeops 3.24.0 → 3.26.0

package/bin/install.js

@@ -3,6 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { checkPath, checkTree, copyFile, writeFile, mkdir } = require('./lib/install-paths')
 
 const SKILLS_SRC = path.join(__dirname, '..', 'skills')
 const HOOKS_SRC = path.join(__dirname, '..', 'hooks')
@@ -17,28 +18,30 @@ const HOOK_SCRIPTS = ['session-start', 'session-stop', 'pre-compact']
 const ENGAGEMENTS_ROOT = path.join(os.homedir(), 'fde-engagements')
 
 function copyDir(src, dest) {
-  fs.mkdirSync(dest, { recursive: true })
+  checkTree(src, dest)
+  mkdir(dest)
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name)
     const destPath = path.join(dest, entry.name)
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath)
     } else {
-      fs.copyFileSync(srcPath, destPath)
+      copyFile(srcPath, destPath)
     }
   }
 }
 
 function copyTemplateTree(src, dest, onlyMissing) {
+  checkTree(src, dest)
   let merged = 0
-  fs.mkdirSync(dest, { recursive: true })
+  mkdir(dest)
   for (const name of fs.readdirSync(src)) {
     const srcPath = path.join(src, name)
     const destPath = path.join(dest, name)
     if (fs.statSync(srcPath).isDirectory()) {
       merged += copyTemplateTree(srcPath, destPath, onlyMissing)
     } else if (!onlyMissing || !fs.existsSync(destPath)) {
-      fs.copyFileSync(srcPath, destPath)
+      copyFile(srcPath, destPath)
       if (onlyMissing) merged++
     }
   }
@@ -62,17 +65,17 @@ const MANAGED_MARKER = '.fdeops-managed'
 function markManaged(dir) {
   let version = 'unknown'
   try { version = require(path.join(__dirname, '..', 'package.json')).version } catch (_) {}
-  try {
-    fs.writeFileSync(
-      path.join(dir, MANAGED_MARKER),
-      `managed-by: fdeops\nversion: ${version}\ninstalled: ${new Date().toISOString()}\n` +
-      'Delete this file to make fdeops treat the directory as yours and leave it alone.\n',
-    )
-  } catch (_) {}
+  writeFile(
+    path.join(dir, MANAGED_MARKER),
+    `managed-by: fdeops\nversion: ${version}\ninstalled: ${new Date().toISOString()}\n` +
+    'Delete this file to make fdeops treat the directory as yours and leave it alone.\n',
+  )
 }
 
 function isManaged(dir) {
-  return fs.existsSync(path.join(dir, MANAGED_MARKER))
+  const marker = path.join(dir, MANAGED_MARKER)
+  checkPath(marker)
+  return fs.existsSync(marker) && /^managed-by: fdeops$/m.test(fs.readFileSync(marker, 'utf8'))
 }
 
 // A skill "directory" that is really a symlink points somewhere outside
@@ -89,6 +92,7 @@ function isLink(p) {
 // directory whose name matches one we ship, and only to overwrite - never to delete.
 function wasInstalledByUs(dir) {
   try {
+    checkPath(path.join(dir, 'SKILL.md'))
     const md = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8')
     const fm = (md.match(/^---\n([\s\S]*?)\n---/) || [])[1]
     if (!fm) return false
@@ -106,6 +110,7 @@ const LEGACY_SKILL_DIRS = [
 ]
 
 function removeLegacySkills(opts = {}) {
+  checkPath(GLOBAL_SKILLS_DIR)
   let removed = 0
   const skipped = []
   const links = []
@@ -128,24 +133,26 @@ function installSkillDirs(opts = {}) {
   const skipped = []
   const links = []
   const failed = []
-  fs.mkdirSync(GLOBAL_SKILLS_DIR, { recursive: true })
+  mkdir(GLOBAL_SKILLS_DIR)
   for (const entry of fs.readdirSync(SKILLS_SRC, { withFileTypes: true })) {
     const src = path.join(SKILLS_SRC, entry.name)
     const dest = path.join(GLOBAL_SKILLS_DIR, entry.name)
-    if (!entry.isDirectory()) { fs.copyFileSync(src, dest); continue }
+    if (!entry.isDirectory()) { copyFile(src, dest); continue }
     if (isLink(dest)) { links.push(entry.name); continue }
-    if (fs.existsSync(dest) && !isManaged(dest) && !opts.force) {
-      // Installs predating the marker are still ours: adopt a same-named dir
-      // whose SKILL.md is recognizably fdeops', so upgrades keep working.
-      if (!wasInstalledByUs(dest)) {
-        skipped.push(entry.name)
-        continue
-      }
-      console.log(`  adopt  ~/.claude/skills/${entry.name} (earlier fdeops install)`)
-    }
-    // One unwritable skill dir must not abort the install with a stack trace:
-    // say it in human terms, place the rest, and exit non-zero at the end.
     try {
+      checkTree(src, dest)
+      checkPath(path.join(dest, MANAGED_MARKER))
+      if (fs.existsSync(dest) && !isManaged(dest) && !opts.force) {
+        // Installs predating the marker are still ours: adopt a same-named dir
+        // whose SKILL.md is recognizably fdeops', so upgrades keep working.
+        if (!wasInstalledByUs(dest)) {
+          skipped.push(entry.name)
+          continue
+        }
+        console.log(`  adopt  ~/.claude/skills/${entry.name} (earlier fdeops install)`)
+      }
+      // One unwritable skill dir must not abort the install with a stack trace:
+      // say it in human terms, place the rest, and exit non-zero at the end.
       copyDir(src, dest)
       markManaged(dest)
     } catch (e) {
@@ -174,6 +181,7 @@ function reportCollisions(paths, verb) {
 
 function reportLinks(names) {
   if (!names.length) return
+  installIncomplete = true
   console.log(`  skip   ${names.length} skill path(s) that are symlinks - fdeops will not write through them:`)
   for (const name of names) console.log(`           ~/.claude/skills/${name} -> ${readLinkQuiet(path.join(GLOBAL_SKILLS_DIR, name))}`)
   console.log('         remove the link if you want fdeops to install at that path itself')
@@ -190,7 +198,7 @@ function reportFailures(failures) {
   installIncomplete = true
   console.log(`  error  ${failures.length} skill dir(s) could not be written:`)
   for (const f of failures) {
-    const why = f.code === 'EACCES' || f.code === 'EPERM' ? 'permission denied' : f.code
+    const why = f.code === 'EACCES' || f.code === 'EPERM' ? 'permission denied' : f.code === 'UNSAFE_PATH' ? 'unsafe symlink or non-regular path' : f.code
     console.log(`           ~/.claude/skills/${f.name} - ${why} at ${f.path}`)
   }
   console.log('         fix the permissions (or remove the directory) and re-run - the rest of the install continued')
@@ -204,26 +212,26 @@ function installSkills(opts = {}) {
   reportCollisions(placed.skipped, 'overwriting them')
   reportLinks([...new Set([...legacy.links, ...placed.links])])
   reportFailures(placed.failed)
-  fs.mkdirSync(GLOBAL_HOOKS_DIR, { recursive: true })
+  mkdir(GLOBAL_HOOKS_DIR)
   for (const name of HOOK_SCRIPTS) {
     const src = path.join(HOOKS_SRC, name)
     if (!fs.existsSync(src)) continue
     const dest = path.join(GLOBAL_HOOKS_DIR, `fdeops-${name}`)
-    fs.copyFileSync(src, dest)
+    copyFile(src, dest)
     try {
       fs.chmodSync(dest, '755')
     } catch (_) {}
   }
   const globalPointer = path.join(os.homedir(), '.claude', 'FDEOPS-CLAUDE.md')
   if (!fs.existsSync(globalPointer)) {
-    fs.copyFileSync(CLAUDE_MD_SRC, globalPointer)
+    copyFile(CLAUDE_MD_SRC, globalPointer)
   }
-  fs.copyFileSync(CLAUDE_MD_SRC, path.join(os.homedir(), '.claude', 'FDEOPS-CLAUDE.md.template'))
+  copyFile(CLAUDE_MD_SRC, path.join(os.homedir(), '.claude', 'FDEOPS-CLAUDE.md.template'))
 
   // the fde CLI + templates, so the skill can call it from any workspace
   const cliHome = path.join(os.homedir(), '.claude', 'fdeops')
-  fs.mkdirSync(cliHome, { recursive: true })
-  fs.copyFileSync(path.join(__dirname, 'fde.js'), path.join(cliHome, 'fde.js'))
+  mkdir(cliHome)
+  copyFile(path.join(__dirname, 'fde.js'), path.join(cliHome, 'fde.js'))
   copyDir(LIB_SRC, path.join(cliHome, 'lib'))
   try { fs.chmodSync(path.join(cliHome, 'fde.js'), '755') } catch (_) {}
   copyDir(FDE_TEMPLATES_SRC, path.join(cliHome, 'templates', '.fde'))
@@ -245,7 +253,8 @@ const ADAPTER_TARGETS = [
 const FDE_MARKER = '<!-- fdeops adapter - points your AI tool at @fde; safe to keep -->'
 
 function placePointer(destPath, content, label, appendable) {
-  fs.mkdirSync(path.dirname(destPath), { recursive: true })
+  checkPath(destPath)
+  mkdir(path.dirname(destPath))
   if (fs.existsSync(destPath)) {
     const existing = fs.readFileSync(destPath, 'utf8')
     if (/FDEOS|fdeops/i.test(existing)) {
@@ -256,16 +265,17 @@ function placePointer(destPath, content, label, appendable) {
       console.log(`  skip   ${label} (exists - left untouched)`)
       return
     }
-    fs.writeFileSync(destPath, `${existing.trimEnd()}\n\n${FDE_MARKER}\n\n${content}`)
+    writeFile(destPath, `${existing.trimEnd()}\n\n${FDE_MARKER}\n\n${content}`)
     console.log(`  append ${label}`)
     return
   }
-  fs.writeFileSync(destPath, content)
+  writeFile(destPath, content)
   console.log(`  write  ${label}`)
 }
 
 function cmdAdapters(targetDir, opts = {}) {
   const dest = path.resolve(targetDir || process.cwd())
+  checkPath(dest)
   console.log('')
   console.log(`  fdeops cross-platform adapters → ${dest}`)
   console.log('  One brain (skills/fde/SKILL.md). These are thin pointers per tool.')
@@ -275,6 +285,7 @@ function cmdAdapters(targetDir, opts = {}) {
   // that file - `adapters` alone wrote pointers to a brain that didn't exist
   // yet, a dangling reference for anyone following the documented Cursor/Codex
   // path. installSkills() is idempotent (safe to call every run).
+  checkPath(path.join(GLOBAL_SKILLS_DIR, 'fde', 'SKILL.md'))
   if (!fs.existsSync(path.join(GLOBAL_SKILLS_DIR, 'fde', 'SKILL.md'))) {
     installSkills(opts)
     console.log('  Skills → ~/.claude/skills/  (installed - the pointers below need this)')
@@ -282,11 +293,16 @@ function cmdAdapters(targetDir, opts = {}) {
   }
   for (const a of ADAPTER_TARGETS) {
     if (!fs.existsSync(a.src)) { console.log(`  skip   ${a.label} (template missing)`); continue }
-    placePointer(path.join(dest, a.dest), fs.readFileSync(a.src, 'utf8'), a.label, a.appendable)
+    try {
+      placePointer(path.join(dest, a.dest), fs.readFileSync(a.src, 'utf8'), a.label, a.appendable)
+    } catch (e) {
+      installIncomplete = true
+      console.error(`  error  ${a.label}: ${e.message}`)
+    }
   }
   console.log('')
   console.log('  Open this workspace in Claude Code, Cursor, Codex, Gemini CLI, or Copilot')
-  console.log('  and type @fde - each tool now routes to the same engagement brain.')
+  console.log(installIncomplete ? '  Some adapters could not be installed; fix the errors above and run again.' : '  and type @fde - each tool now routes to the same engagement brain.')
   console.log('')
 }
 
@@ -304,7 +320,7 @@ function cmdInit(engagementName) {
 
   const pointer = path.join(root, 'ENGAGEMENT.md')
   if (!fs.existsSync(pointer)) {
-    fs.writeFileSync(
+    writeFile(
       pointer,
       `# ${engagementName}\n\nEngagement root: \`${fdeDir}\`\n\nPoint your **AI coding agent** at this folder (not a human colleague). Add to ~/.claude/FDEOPS-CLAUDE.md:\n\n\`\`\`\nFDEOPS_ENGAGEMENT=${fdeDir}\n\`\`\`\n\nOpen your workspace. In the AI chat, type \`@fde\`.\n`,
     )
@@ -435,16 +451,23 @@ function handOffToCli(verb) {
   require(path.join(__dirname, 'fde.js'))
 }
 
-if (!raw && askedVersion) {
-  console.log(require(path.join(__dirname, '..', 'package.json')).version)
-} else if (!raw && askedHelp) {
-  handOffToCli('help')
-} else if (arg === 'init') {
-  cmdInit(positional[1])
-} else if (arg === 'adapters') {
-  cmdAdapters(positional[1], { force })
-} else if (arg && arg !== 'install') {
-  handOffToCli(arg)
-} else {
-  cmdInstall({ force })
+try {
+  if (!raw && askedVersion) {
+    console.log(require(path.join(__dirname, '..', 'package.json')).version)
+  } else if (!raw && askedHelp) {
+    handOffToCli('help')
+  } else if (arg === 'init') {
+    cmdInit(positional[1])
+  } else if (arg === 'adapters') {
+    cmdAdapters(positional[1], { force })
+  } else if (arg && arg !== 'install') {
+    handOffToCli(arg)
+  } else {
+    cmdInstall({ force })
+  }
+
+} catch (e) {
+  console.error(`  fdeops: ${e.message}`)
+  process.exitCode = 1
 }
+if (installIncomplete) process.exitCode = 1

package/bin/lib/context.js

@@ -0,0 +1,85 @@
+'use strict'
+
+const DEFAULT_BYTES = 16384
+const MIN_BYTES = 4096
+const MAX_BYTES = 65536
+const OMITTED = '\n[Excerpt truncated; retrieve the source before relying on omitted details.]'
+
+// A byte ceiling is deterministic across hosts. It is deliberately not called
+// a token count: tokenization varies by model and language.
+function clipUtf8(text, bytes) {
+  if (Buffer.byteLength(text) <= bytes) return text
+  const buf = Buffer.from(text)
+  let end = Math.max(0, bytes)
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--
+  return buf.subarray(0, end).toString('utf8')
+}
+function budgetArgs(args) {
+  const rest = [...args]
+  let maxBytes = DEFAULT_BYTES
+  const at = rest.indexOf('--max-bytes')
+  if (at !== -1) {
+    const raw = rest[at + 1]
+    maxBytes = Number(raw)
+    if (!/^\d+$/.test(raw || '') || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_BYTES || maxBytes > MAX_BYTES) {
+      throw new Error(`--max-bytes must be an integer from ${MIN_BYTES} to ${MAX_BYTES}`)
+    }
+    rest.splice(at, 2)
+    if (rest.includes('--max-bytes')) throw new Error('supply --max-bytes only once')
+  }
+  return { args: rest, maxBytes }
+}
+function boundedSections(sections, maxBytes = DEFAULT_BYTES) {
+  const footer = '\n\nCONTEXT: selected excerpts, not the complete record or proof of approval. Use fde recall <topic> for relevant evidence. If policy or constraints are truncated, retrieve them before acting. Verify conflicting decisions.\n'
+  let out = ''
+  const filled = sections.filter(s => s && s.trim())
+  for (let i = 0; i < filled.length; i++) {
+    const available = maxBytes - Buffer.byteLength(out + footer) - 2
+    const share = Math.max(0, Math.floor(available / (filled.length - i)))
+    const text = filled[i]
+    const next = Buffer.byteLength(text) <= share ? text : clipUtf8(text, Math.max(0, share - Buffer.byteLength(OMITTED))) + OMITTED
+    out += (out ? '\n\n' : '') + next
+  }
+  return out + footer
+}
+
+// Literal, client-scoped lexical retrieval. Retain independently matching
+// records, including conflicting/older ones; recency never means truth.
+function recallSections(documents, query, maxHits = 12) {
+  const words = [...new Set(query.toLocaleLowerCase().split(/\s+/).filter(Boolean))].slice(0, 16)
+  const hits = []
+  for (const { file, text } of documents) {
+    const lines = text.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const lower = line.toLocaleLowerCase()
+      const score = words.reduce((n, word) => n + Number(lower.includes(word)), 0)
+      if (!score) continue
+      const first = Math.max(0, i - 1)
+      const last = Math.min(lines.length, i + 3)
+      const excerpt = lines.slice(first, last).map(l => Buffer.byteLength(l) <= 1024 ? l : clipUtf8(l, 900) + OMITTED).join('\n')
+      hits.push({ file, line: first + 1, end: last, score, text: excerpt.trim() })
+    }
+  }
+  hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file) || b.line - a.line)
+  // Round-robin files, taking recent and older matches so a long topic does
+  // not hide its latest change or original constraint. Omission stays explicit.
+  const groups = new Map()
+  for (const hit of hits) {
+    if (!groups.has(hit.file)) groups.set(hit.file, [])
+    groups.get(hit.file).push(hit)
+  }
+  const selected = []
+  let oldest = false
+  while (selected.length < maxHits && [...groups.values()].some(g => g.length)) {
+    for (const group of groups.values()) {
+      if (group.length && selected.length < maxHits) selected.push(oldest ? group.pop() : group.shift())
+    }
+    oldest = !oldest
+  }
+  return {
+    total: hits.length,
+    sections: selected.map(h => `${h.file}:${h.line}-${h.end} (lines in redacted view)\n${h.text}`),
+  }
+}
+module.exports = { DEFAULT_BYTES, clipUtf8, budgetArgs, boundedSections, recallSections }

package/bin/lib/fieldbook-client.js

@@ -6,6 +6,10 @@ module.exports = function fieldbookClient() {
   const views = all('.fb-view')
   const nav = all('.fb-nav')
   const search = document.getElementById('fb-search')
+  const filter = document.getElementById('fb-filter')
+  const rail = document.getElementById('fb-client-rail')
+  const clientsButton = document.getElementById('fb-clients-btn')
+  const mobile = window.matchMedia('(max-width:640px)')
   const main = document.querySelector('.fb-main')
   const status = document.getElementById('fb-status')
   const palette = document.getElementById('fb-palette-dialog')
@@ -15,6 +19,13 @@ module.exports = function fieldbookClient() {
   let returnFocus = null
   let active = 0
   const currentId = () => document.querySelector('.fb-view:not([hidden])').id.replace('view-', '')
+  function showClients(show) {
+    rail.classList.toggle('is-collapsed', !show)
+    clientsButton.setAttribute('aria-expanded', String(show))
+  }
+  showClients(!mobile.matches)
+  mobile.addEventListener('change', event => showClients(!event.matches))
+  clientsButton.addEventListener('click', () => showClients(clientsButton.getAttribute('aria-expanded') !== 'true'))
   function selectView(id, updateHash = true, focus = false) {
     if (id === 'fb-main') { id = 'today'; updateHash = false }
     if (!document.getElementById('view-' + id)) id = 'today'
@@ -27,7 +38,10 @@ module.exports = function fieldbookClient() {
     })
     if (updateHash && location.hash !== '#' + id) location.hash = id
     main.scrollTop = 0
-    if (focus) document.querySelector('.fb-view:not([hidden]) h1').focus()
+    if (focus) {
+      document.querySelector('.fb-view:not([hidden]) h1').focus()
+      if (mobile.matches) showClients(false)
+    }
   }
   const hashId = () => location.hash.slice(1)
   selectView(hashId() || 'today', false)
@@ -47,22 +61,34 @@ module.exports = function fieldbookClient() {
     const start = Math.max(0, i - 24), end = Math.min(raw.length, i + term.length + 40)
     return (start ? '…' : '') + esc(raw.slice(start, i)) + '<mark>' + esc(raw.slice(i, i + term.length)) + '</mark>' + esc(raw.slice(i + term.length, end)) + (end < raw.length ? '…' : '')
   }
-  search.addEventListener('input', () => {
+  function filterClients() {
     const term = search.value.trim().toLowerCase()
-    let count = 0
+    const matches = new Set()
     nav.filter(n => n.dataset.target !== 'today').forEach(n => {
-      const raw = n.dataset.search || ''
-      const hit = !term || raw.includes(term)
+      const raw = (n.dataset.search || '').toLowerCase()
+      const inGroup = filter.value === 'all' || (n.dataset.attention === 'true') === (filter.value === 'attention')
+      const hit = inGroup && (!term || raw.includes(term))
       n.classList.toggle('hide', !hit)
-      if (hit) count++
+      if (hit) matches.add(n.dataset.target)
       const reason = n.querySelector('.fb-nav-reason')
       if (term && hit) reason.innerHTML = snippet(raw, term)
       else reason.textContent = n.dataset.defaultReason || ''
       reason.classList.toggle('hide', !reason.textContent)
     })
-    document.getElementById('fb-search-empty').hidden = !term || count > 0
-    document.getElementById('fb-search-count').textContent = term ? count + ' matching engagement' + (count === 1 ? '' : 's') : ''
-  })
+    const count = matches.size
+    all('[data-client]').forEach(row => row.classList.toggle('hide', !matches.has(row.dataset.client)))
+    const filtering = Boolean(term) || filter.value !== 'all'
+    document.getElementById('fb-search-empty').hidden = !filtering || count > 0
+    const empty = document.getElementById('fb-results-empty')
+    if (empty) empty.hidden = !filtering || count > 0
+    all('[data-filter-section]').forEach(section => { section.hidden = !Array.from(section.querySelectorAll('[data-client]')).some(row => !row.classList.contains('hide')) })
+    const total = nav.length - 1
+    document.getElementById('fb-search-count').textContent = count + ' of ' + total + ' client' + (total === 1 ? '' : 's') + (filtering ? ' match' : '')
+  }
+  search.addEventListener('input', filterClients)
+  filter.addEventListener('change', filterClients)
+  all('[data-reset-filters]').forEach(button => button.addEventListener('click', () => { search.value = ''; filter.value = 'all'; filterClients() }))
+  filterClients()
 
   function toggleTheme() {
     const next = document.documentElement.dataset.fdeTheme === 'dark' ? 'light' : 'dark'
@@ -114,6 +140,7 @@ module.exports = function fieldbookClient() {
     if (!it) return
     palette.close()
     if (it.dataset.target === '__theme__') toggleTheme()
+    else if (it.dataset.target === '__print__') window.print()
     else selectView(it.dataset.target, true, true)
   }
   document.getElementById('fb-palette-btn').addEventListener('click', openPalette)
@@ -134,6 +161,10 @@ module.exports = function fieldbookClient() {
     try {
       await navigator.clipboard.writeText(text)
       status.textContent = 'Prompt copied. Paste it into your coding agent; review changes before saving.'
+      const label = button.textContent
+      button.textContent = 'Copied'
+      button.disabled = true
+      setTimeout(() => { button.textContent = label; button.disabled = false }, 1800)
     } catch (_) {
       const input = document.getElementById('fb-prompt-text')
       input.value = text
@@ -154,7 +185,7 @@ module.exports = function fieldbookClient() {
       return
     }
     if (event.target.closest('.fb-table-scroll')) return
-    if (event.key === '/') { event.preventDefault(); search.focus(); return }
+    if (event.key === '/') { event.preventDefault(); showClients(true); search.focus(); return }
     if (event.key === 'j' || event.key === 'k' || (event.target.closest('.fb-rail') && ['ArrowDown', 'ArrowUp'].includes(event.key))) {
       event.preventDefault()
       const ids = nav.filter(n => !n.classList.contains('hide')).map(n => n.dataset.target)