@phenx-inc/ctlsurf 0.17.3 → 0.17.5

package/scripts/setup-ui.cjs

@@ -0,0 +1,161 @@
+// Terminal UI shared by the npm postinstall banner and the launcher's first-run setup.
+// Live redraw only on a TTY; otherwise each step prints one plain line when it settles.
+
+const R = '\x1b[0m'
+const D = '\x1b[90m'
+const G = '\x1b[32m'
+const Y = '\x1b[33m'
+const C = '\x1b[36m'
+
+const LOGO = [
+  '╔═╗╔╦╗╦  ╔═╗╦ ╦╦═╗╔═╗',
+  '║   ║ ║  ╚═╗║ ║╠╦╝╠╣ ',
+  '╚═╝ ╩ ╩═╝╚═╝╚═╝╩╚═╚  ',
+]
+const LOGO_COLORS = [51, 45, 39] // 256-color cyan → blue, one per row
+
+function banner(version) {
+  const logo = LOGO.map((line, i) => `   \x1b[38;5;${LOGO_COLORS[i]}m${line}${R}`)
+  return ['', ...logo, `   ${D}the terminal that remembers · v${version}${R}`, '', ''].join('\n')
+}
+
+function formatBytes(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)} GB`
+  if (n >= 1e6) return `${Math.round(n / 1e6)} MB`
+  return `${Math.round(n / 1e3)} KB`
+}
+
+function formatDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000))
+  const m = Math.floor(s / 60)
+  return m ? `${m}m${String(s % 60).padStart(2, '0')}s` : `${s}s`
+}
+
+const SPIN = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
+const ICONS = {
+  pending: `${D}·${R}`, done: `${G}✓${R}`, fail: `${Y}✗${R}`,
+  warn: `${Y}!${R}`, skip: `${D}–${R}`, ask: `${C}?${R}`,
+}
+const SETTLED = new Set(['done', 'fail', 'warn', 'skip'])
+const BAR = 16
+const LABEL = 23
+
+// progress: undefined → no bar, null → indeterminate sweep, 0..1 → filled bar with percent
+function bar(progress, frame) {
+  if (progress === null) {
+    const span = BAR - 4
+    const pos = Math.abs((frame % (span * 2)) - span)
+    return `${D}▕${'░'.repeat(pos)}${C}▓██▓${D}${'░'.repeat(span - pos)}▏${R}`
+  }
+  const p = Math.min(1, Math.max(0, progress))
+  const n = Math.round(p * BAR)
+  return `${D}▕${C}${'█'.repeat(n)}${D}${'░'.repeat(BAR - n)}▏${R} ${String(Math.floor(p * 100)).padStart(3)}%`
+}
+
+// Pad or truncate to a visible width, skipping ANSI escapes.
+function fit(text, width) {
+  const parts = text.match(/\x1b\[[0-9;?]*[A-Za-z]|[\s\S]/gu) || []
+  const visible = parts.filter(p => p[0] !== '\x1b').length
+  let out = ''
+  let n = 0
+  for (const p of parts) {
+    if (p[0] === '\x1b') { out += p; continue }
+    if (visible > width && n === width - 1) { out += '…'; n++; break }
+    out += p
+    n++
+  }
+  return out + R + ' '.repeat(Math.max(0, width - n))
+}
+
+class Steps {
+  constructor(title, labels, out = process.stdout) {
+    this.title = title
+    this.out = out
+    this.live = !!out.isTTY
+    this.steps = labels.map(label => ({ label, state: 'pending', note: '', detail: '', progress: undefined, printed: false }))
+    this.drawn = 0
+    this.frame = 0
+    this.timer = null
+    this.onSigint = () => { this.finish(); this.out.write('\n'); process.exit(130) }
+  }
+
+  start() {
+    if (this.live) {
+      this.out.write('\x1b[?25l')
+      this.timer = setInterval(() => { this.frame++; this.render() }, 80)
+      process.on('SIGINT', this.onSigint)
+    }
+    this.render()
+    return this
+  }
+
+  set(i, patch) {
+    const step = this.steps[i]
+    Object.assign(step, patch)
+    if (!SETTLED.has(step.state)) step.printed = false
+    if (!this.live && SETTLED.has(step.state) && !step.printed) {
+      step.printed = true
+      const note = step.note ? `  ${D}${step.note}${R}` : ''
+      const detail = step.detail ? `\n      ${D}${step.detail}${R}` : ''
+      this.out.write(`  ${ICONS[step.state]} ${step.label}${note}${detail}\n`)
+    }
+    this.render()
+  }
+
+  row(step) {
+    const icon = step.state === 'run' ? `${C}${SPIN[this.frame % SPIN.length]}${R}` : ICONS[step.state]
+    const label = step.state === 'pending' ? `${D}${step.label}${R}` : step.label
+    let right = step.state === 'run' && step.progress !== undefined ? bar(step.progress, this.frame) + ' ' : ''
+    if (step.note) right += `${D}${step.note}${R}`
+    return `${icon} ${fit(label, LABEL)} ${right}`
+  }
+
+  render() {
+    if (!this.live) return
+    const width = Math.max(44, Math.min(68, (this.out.columns || 80) - 6))
+    const lines = [`${D}┌─ ${R}${this.title}${D} ${'─'.repeat(Math.max(0, width - 1 - this.title.length))}┐${R}`]
+    for (const step of this.steps) {
+      lines.push(`${D}│${R} ${fit(this.row(step), width)} ${D}│${R}`)
+      if (step.detail) lines.push(`${D}│${R} ${fit(`    ${D}${step.detail}`, width)} ${D}│${R}`)
+    }
+    lines.push(`${D}└${'─'.repeat(width + 2)}┘${R}`)
+    const up = this.drawn ? `\x1b[${this.drawn}A\r\x1b[J` : ''
+    this.out.write(up + lines.map(l => `  ${l}`).join('\n') + '\n')
+    this.drawn = lines.length
+  }
+
+  // Ask below the box, then fold the prompt lines back into the next redraw.
+  async confirm(lines, question, defaultYes = true) {
+    if (this.timer) { clearInterval(this.timer); this.timer = null }
+    this.render()
+    const text = lines.map(l => `     ${l}`).join('\n') + '\n'
+    if (this.live) this.out.write('\x1b[?25h')
+    this.out.write('\n' + text)
+    const answer = await new Promise(resolve => {
+      const readline = require('readline')
+      const rl = readline.createInterface({ input: process.stdin, output: this.out })
+      rl.on('SIGINT', () => { rl.close(); process.kill(process.pid, 'SIGINT') })
+      rl.question(`     ${question} ${D}${defaultYes ? '(Y/n)' : '(y/N)'}${R} `, a => { rl.close(); resolve(a.trim()) })
+    })
+    if (this.live) {
+      this.drawn += lines.length + 2
+      this.out.write('\x1b[?25l')
+      this.timer = setInterval(() => { this.frame++; this.render() }, 80)
+      this.render()
+    } else {
+      this.out.write('\n')
+    }
+    return answer ? /^y(es)?$/i.test(answer) : defaultYes
+  }
+
+  finish() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null }
+    this.render()
+    if (this.live) {
+      this.out.write('\x1b[?25h')
+      process.removeListener('SIGINT', this.onSigint)
+    }
+  }
+}
+
+module.exports = { banner, formatBytes, formatDuration, Steps, colors: { R, D, G, Y, C } }

package/scripts/test-work-map-ui.cjs

@@ -57,6 +57,11 @@ async function main() {
     await win.loadFile(path.join(temp, 'index.html'))
     const run = code => win.webContents.executeJavaScript(code)
     await run(`new Promise(resolve=>setTimeout(resolve,150))`)
+    assert.equal(await run(`document.querySelector('.work-map-goal-heading').getAttribute('aria-expanded')`), 'true')
+    assert.equal(await run(`document.querySelector('.work-map-branch-heading').getAttribute('aria-expanded')`), 'false')
+    assert.equal(await run(`document.querySelectorAll('.work-map-step').length`), 0, 'event groups start collapsed')
+    await run(`document.querySelector('.work-map-branch-heading').click()`)
+    await run(`new Promise(resolve=>setTimeout(resolve,30))`)
     assert.equal(await run(`document.querySelectorAll('.work-map-step').length`), 29, 'choices and actions must share one thread')
     assert.equal(await run(`document.querySelector('.work-map-view')`), null, 'there are no separate decision/activity tabs')
     assert.match(await run(`document.querySelector('.work-map-reason').textContent`), /Why.*does not interrupt/)
@@ -111,6 +116,9 @@ async function main() {
     await run(`window.emitMap({thinkingStatus:'unavailable',nodes:window.exampleNodes.filter(n=>n.id!=='thought')})`)
     await run(`new Promise(resolve=>setTimeout(resolve,30))`)
     assert.match(await run(`document.querySelector('.work-map-thinking-status').textContent`), /omits readable thinking/)
+    assert.equal(await run(`document.querySelectorAll('.work-map-step').length`), 0, 'events collected after clearing also start collapsed')
+    await run(`document.querySelector('.work-map-branch-heading').click()`)
+    await run(`new Promise(resolve=>setTimeout(resolve,30))`)
     assert.equal(await run(`document.querySelectorAll('.work-map-step').length`), 28, 'activity remains visible when thinking is omitted')
     assert.equal(await run(`document.querySelectorAll('.work-map-intent').length`), 0, 'tool activity must not become invented decisions when thinking is omitted')
     for (const state of ['checking', 'unavailable']) {
@@ -120,7 +128,7 @@ async function main() {
       assert(await run(`document.querySelector('[role=switch]').disabled`))
       assert(await run(`document.querySelector('select').disabled`))
     }
-    console.log('PASS unified chronological thread, salient excerpts and reasons, source receipts, action links, omitted-thinking notice, controls and scroll')
+    console.log('PASS collapsed event groups, unified chronological thread, salient excerpts and reasons, source receipts, action links, omitted-thinking notice, controls and scroll')
     console.log('Screenshot:', screenshot)
   } finally {
     win?.destroy()

package/scripts/work-map-setup.cjs

@@ -0,0 +1,127 @@
+// Launcher side of the Work map model: find an existing Clef-Flash runtime, or prepare one
+// with prepare-work-map.py while reporting phases and downloaded bytes.
+// The runtime lives outside node_modules, so `npm update` never removes or re-downloads it.
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { spawn } = require('child_process')
+
+// mlx-community/clef-flash-8bit @ the revision pinned in prepare-work-map.py
+const MODEL_BYTES = 10_690_311_092
+// Weights + Python/MLX env (~0.6 GB) + uv cache, with headroom
+const DISK_NEEDED = 12.5e9
+const DEFAULT_DIR = path.join(os.homedir(), '.ctlsurf', 'clef-flash')
+
+function defaultPaths() {
+  return { pythonPath: path.join(DEFAULT_DIR, 'env', 'bin', 'python'), modelPath: path.join(DEFAULT_DIR, 'model') }
+}
+
+// Files of the pinned revision besides the indexed weight shards. An interrupted
+// download can have clef_mlx.py (what ClefWorker checks) without the weights.
+const REQUIRED_FILES = ['clef_mlx.py', 'config.json', 'tokenizer.json', 'joint_head.safetensors', 'model.safetensors.index.json']
+
+function modelReady({ pythonPath, modelPath } = {}) {
+  if (!pythonPath || !modelPath || !fs.existsSync(pythonPath)) return false
+  try {
+    const index = JSON.parse(fs.readFileSync(path.join(modelPath, 'model.safetensors.index.json'), 'utf-8'))
+    return [...REQUIRED_FILES, ...Object.values(index.weight_map)].every(f => fs.existsSync(path.join(modelPath, f)))
+  } catch {
+    return false
+  }
+}
+
+function findModel(saved = {}) {
+  return [
+    { pythonPath: saved.pythonPath, modelPath: saved.modelPath },
+    { pythonPath: process.env.CTLSURF_CLEF_PYTHON, modelPath: process.env.CTLSURF_CLEF_MODEL },
+    defaultPaths(),
+  ].find(modelReady) || null
+}
+
+function findUv() {
+  const dirs = (process.env.PATH || '').split(path.delimiter)
+    .concat([path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), '.cargo', 'bin'), '/opt/homebrew/bin', '/usr/local/bin'])
+  for (const dir of dirs) {
+    const uv = path.join(dir, 'uv')
+    try { fs.accessSync(uv, fs.constants.X_OK); return uv } catch { /* keep looking */ }
+  }
+  return null
+}
+
+function freeBytes() {
+  let dir = DEFAULT_DIR
+  while (!fs.existsSync(dir)) dir = path.dirname(dir)
+  try {
+    const s = fs.statfsSync(dir)
+    return s.bavail * s.bsize
+  } catch {
+    return null
+  }
+}
+
+// Includes huggingface_hub's in-flight files under model/.cache, so the count grows during a download.
+function dirBytes(dir) {
+  let total = 0
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return 0 }
+  for (const e of entries) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) total += dirBytes(p)
+    else if (e.isFile()) { try { total += fs.statSync(p).size } catch { /* moved mid-scan */ } }
+  }
+  return total
+}
+
+// onPhase('env' | 'deps' | 'model'), onBytes(downloadedBytes). Resolves with the ready paths.
+function prepareModel({ uv, onPhase = () => {}, onBytes = () => {} }) {
+  fs.mkdirSync(DEFAULT_DIR, { recursive: true })
+  const logPath = path.join(DEFAULT_DIR, 'prepare.log')
+  const log = fs.createWriteStream(logPath)
+  const script = path.join(__dirname, 'prepare-work-map.py')
+  const { modelPath } = defaultPaths()
+
+  return new Promise((resolve, reject) => {
+    // uv supplies Python 3.12, so no system python3 (or Xcode CLT prompt) is involved.
+    const child = spawn(uv, ['run', '--no-project', '--python', '3.12', script, '--progress', '--directory', DEFAULT_DIR], {
+      cwd: DEFAULT_DIR,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        PATH: `${path.dirname(uv)}${path.delimiter}${process.env.PATH || ''}`,
+        UV_CACHE_DIR: path.join(DEFAULT_DIR, 'uv'),
+      },
+    })
+    let poll = null
+    let buffer = ''
+    child.stdout.on('data', chunk => {
+      buffer += String(chunk)
+      let newline
+      while ((newline = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newline)
+        buffer = buffer.slice(newline + 1)
+        const phase = /^::phase (\w+)/.exec(line)
+        if (!phase) { log.write(line + '\n'); continue }
+        onPhase(phase[1])
+        if (phase[1] === 'model' && !poll) {
+          onBytes(dirBytes(modelPath))
+          poll = setInterval(() => onBytes(dirBytes(modelPath)), 500)
+        }
+      }
+    })
+    child.stderr.pipe(log, { end: false })
+    child.on('error', err => { clearInterval(poll); log.end(); reject(err) })
+    child.on('close', code => {
+      clearInterval(poll)
+      log.end(() => {
+        const paths = defaultPaths()
+        if (code === 0 && modelReady(paths)) { resolve(paths); return }
+        let tail = ''
+        try { tail = fs.readFileSync(logPath, 'utf-8').trim().split('\n').slice(-1)[0] } catch { /* no log */ }
+        reject(new Error(tail || `prepare-work-map.py exited with code ${code}`))
+      })
+    })
+  })
+}
+
+module.exports = { MODEL_BYTES, DISK_NEEDED, DEFAULT_DIR, modelReady, findModel, findUv, freeBytes, prepareModel }

package/src/main/index.ts

@@ -247,9 +247,17 @@ const orchestrator = new Orchestrator(
       updateProjectBadge(orchestrator.getActiveTabProjectPath() || orchestrator.cwd)
     },
   },
-  { appRoot: app.isPackaged ? process.resourcesPath : app.getAppPath(), desktop: true },
+  { appRoot: workMapRoot(), desktop: true },
 )
 
+// app.isPackaged can't tell the two apart: the npm launcher renames Electron's
+// binary to "ctlsurf", which makes it true there too. Only an electron-builder
+// build ships the Clef script under resources/ (extraResources).
+function workMapRoot(): string {
+  const resources = process.resourcesPath
+  return fs.existsSync(path.join(resources, 'scripts', 'work-map-clef.py')) ? resources : app.getAppPath()
+}
+
 // ─── Window ───────────────────────────────────────
 
 function createWindow(): void {

package/src/renderer/components/WorkMapPanel.tsx

@@ -10,7 +10,8 @@ export function WorkMapPanel({ tabId }: { tabId: string }) {
   const [snapshot, setSnapshot] = useState<MapSnapshot | null>(null)
   const [error, setError] = useState<string | null>(null)
   const [saving, setSaving] = useState(false)
-  const [collapsed, setCollapsed] = useState<Set<string>>(new Set())
+  const [collapsedGoals, setCollapsedGoals] = useState<Set<string>>(new Set())
+  const [expandedThreads, setExpandedThreads] = useState<Set<string>>(new Set())
   const [selected, setSelected] = useState<string | null>(null)
   const [following, setFollowing] = useState(true)
   const [paths, setPaths] = useState({ pythonPath: '', modelPath: '' })
@@ -62,7 +63,14 @@ export function WorkMapPanel({ tabId }: { tabId: string }) {
     finally { if (alive.current) setSaving(false) }
   }
 
-  const toggleBranch = (id: string) => setCollapsed(prev => {
+  const toggleGoal = (id: string) => setCollapsedGoals(prev => {
+    const next = new Set(prev)
+    if (next.has(id)) next.delete(id)
+    else next.add(id)
+    return next
+  })
+
+  const toggleThread = (id: string) => setExpandedThreads(prev => {
     const next = new Set(prev)
     if (next.has(id)) next.delete(id)
     else next.add(id)
@@ -188,20 +196,20 @@ export function WorkMapPanel({ tabId }: { tabId: string }) {
           : 'Stated decisions, readable thinking, actions, and results appear in one continuous thread. Open any card to inspect its source.'}</p>
       </div> : <div className="work-map-forest">
         {goals.map((goal, i) => <article className="work-map-goal" key={goal.id}>
-          <button className="work-map-goal-heading" onClick={() => toggleBranch(goal.id)} aria-expanded={!collapsed.has(goal.id)} title={goal.evidence[0]?.text}>
+          <button className="work-map-goal-heading" onClick={() => toggleGoal(goal.id)} aria-expanded={!collapsedGoals.has(goal.id)} title={goal.evidence[0]?.text}>
             <span className="work-map-goal-icon" aria-hidden="true">◎</span><span><span className="work-map-kicker">GOAL {String(i + 1).padStart(2, '0')}</span><strong>{goal.title}</strong></span>
-            <span className="work-map-caret">{collapsed.has(goal.id) ? '▸' : '▾'}</span>
+            <span className="work-map-caret">{collapsedGoals.has(goal.id) ? '▸' : '▾'}</span>
           </button>
-          {!collapsed.has(goal.id) && <div className="work-map-branches">
+          {!collapsedGoals.has(goal.id) && <div className="work-map-branches">
             {threadRuns(goal.id).map(run => {
               const failed = run.nodes.some(n => n.status === 'failed')
               return <div className="work-map-branch" key={run.id}>
-                <button className="work-map-branch-heading" onClick={() => toggleBranch(run.id)} aria-expanded={!collapsed.has(run.id)}>
+                <button className="work-map-branch-heading" onClick={() => toggleThread(run.id)} aria-expanded={expandedThreads.has(run.id)}>
                   <span className={`work-map-branch-point ${failed ? 'failed' : ''}`} />
                   <span className="work-map-branch-label">{run.label}</span><span className="work-map-count">{run.nodes.length}</span>
-                  <span className="work-map-caret">{collapsed.has(run.id) ? '▸' : '▾'}</span>
+                  <span className="work-map-caret">{expandedThreads.has(run.id) ? '▾' : '▸'}</span>
                 </button>
-                {!collapsed.has(run.id) && <ul className="work-map-steps" aria-label="Activity thread">{run.nodes.map(renderStep)}</ul>}
+                {expandedThreads.has(run.id) && <ul className="work-map-steps" aria-label="Activity thread">{run.nodes.map(renderStep)}</ul>}
               </div>
             })}
           </div>}
@@ -213,7 +221,7 @@ export function WorkMapPanel({ tabId }: { tabId: string }) {
     <footer className="work-map-footer"><span>{decisions.length} {decisions.length === 1 ? 'choice' : 'choices'} · {steps.length} events · local</span>
       <button disabled={!steps.length || saving} onClick={async () => {
         setError(null)
-        try { accept(await window.worker.clearWorkMap(tabId)); setCollapsed(new Set()); setSelected(null); setFollowing(true) }
+        try { accept(await window.worker.clearWorkMap(tabId)); setCollapsedGoals(new Set()); setExpandedThreads(new Set()); setSelected(null); setFollowing(true) }
         catch (err) { if (alive.current) setError(String(err)) }
       }}>Clear map</button>
     </footer>