@phenx-inc/ctlsurf 0.17.3 → 0.17.4

package/out/main/index.js

@@ -24918,8 +24918,12 @@ const orchestrator = new Orchestrator(
       updateProjectBadge(orchestrator.getActiveTabProjectPath() || orchestrator.cwd);
     }
   },
-  { appRoot: electron.app.isPackaged ? process.resourcesPath : electron.app.getAppPath(), desktop: true }
+  { appRoot: workMapRoot(), desktop: true }
 );
+function workMapRoot() {
+  const resources = process.resourcesPath;
+  return fs.existsSync(path$1.join(resources, "scripts", "work-map-clef.py")) ? resources : electron.app.getAppPath();
+}
 function createWindow() {
   const saved = orchestrator.settingsData;
   if (saved.themeSource === "light" || saved.themeSource === "dark" || saved.themeSource === "system") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenx-inc/ctlsurf",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "description": "Agent-agnostic terminal and desktop app for ctlsurf — run Claude Code, Codex, or any coding agent with live session logging and remote control",
   "main": "out/main/index.js",
   "bin": {

package/scripts/postinstall.cjs

@@ -1,5 +1,9 @@
+const fs = require('node:fs')
 const { spawnSync } = require('node:child_process')
 const { detectCapability } = require('./check-work-map-gpu.cjs')
+const { banner, formatBytes, colors: { R, D, G, C } } = require('./setup-ui.cjs')
+const { MODEL_BYTES } = require('./work-map-setup.cjs')
+const { version } = require('../package.json')
 
 // Keep the existing best-effort native rebuild, including on Windows.
 try {
@@ -8,8 +12,33 @@ try {
   })
 } catch { /* The launcher also handles missing native builds. */ }
 
+// npm hides lifecycle-script output (foreground-scripts=false), so the banner is written
+// straight to the terminal. No terminal (CI, Windows, detached) → the plain log line only.
+function openTty() {
+  if (process.platform === 'win32' || process.env.CI) return null
+  try { return fs.openSync('/dev/tty', 'w') } catch { return null }
+}
+
 detectCapability({ desktop: true }).then(capability => {
-  console.log(capability.state === 'available'
-    ? `[ctlsurf] Work map hardware detected: ${capability.gpuName}. GPU access is checked again by the desktop app.`
-    : `[ctlsurf] ${capability.reason} Other app features remain available.`)
+  const available = capability.state === 'available'
+  const tty = openTty()
+  if (tty === null) {
+    console.log(available
+      ? `[ctlsurf] Work map hardware detected: ${capability.gpuName}. GPU access is checked again by the desktop app.`
+      : `[ctlsurf] ${capability.reason} Other app features remain available.`)
+    return
+  }
+  const gpu = available
+    ? `${G}✓${R} ${capability.gpuName} · Metal ${D}— work map capable${R}`
+    : `${D}– ${capability.reason}${R}`
+  const next = available
+    ? `Electron runtime + optional work map model ${D}(Clef-Flash, ${formatBytes(MODEL_BYTES)})${R}`
+    : 'Electron runtime'
+  try {
+    fs.writeSync(tty, '\r\x1b[2K' + banner(version)
+      + `   ${G}✓${R} installed\n   ${gpu}\n\n`
+      + `   Run ${C}ctlsurf${R} to finish setup: ${next}\n\n`)
+  } finally {
+    fs.closeSync(tty)
+  }
 }).catch(() => {})

package/scripts/prepare-work-map.py

@@ -11,7 +11,13 @@ import sys
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--directory', type=Path, default=Path.home() / '.ctlsurf' / 'clef-flash')
+    parser.add_argument('--progress', action='store_true', help='print ::phase markers for the ctlsurf launcher')
     args = parser.parse_args()
+
+    def phase(name):
+        if args.progress:
+            print(f'::phase {name}', flush=True)
+
     if sys.platform != 'darwin' or platform.machine() != 'arm64':
         parser.error('Local Clef-Flash requires an Apple Silicon Mac')
     root = args.directory.resolve()
@@ -20,10 +26,16 @@ def main():
     model = root / 'model'
     env = {**os.environ, 'UV_CACHE_DIR': str(root / 'uv'), 'HF_HOME': str(root / 'huggingface'),
            'HF_HUB_DISABLE_TELEMETRY': '1', 'TOKENIZERS_PARALLELISM': 'false'}
+    if args.progress:
+        # The launcher measures bytes on disk; hf-xet only writes each file once it is complete.
+        env.update(HF_HUB_DISABLE_PROGRESS_BARS='1', HF_HUB_DISABLE_XET='1')
+    phase('env')
     if not python.exists():
         subprocess.run(['uv', 'venv', '--python', '3.12', str(root / 'env')], env=env, check=True)
+    phase('deps')
     subprocess.run(['uv', 'pip', 'install', '--python', str(python), 'huggingface_hub',
                     'mlx==0.32.3', 'mlx-lm==0.32.0', 'mlx-vlm==0.7.4'], env=env, check=True)
+    phase('model')
     subprocess.run([str(python), '-c',
                     'from huggingface_hub import snapshot_download; import sys; '
                     'snapshot_download("mlx-community/clef-flash-8bit", '

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/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 {