@threadcrumbs/threadgauge 0.0.0-stage → 0.1.0

package/server/license.mjs

@@ -0,0 +1,100 @@
+import { paidThrough, renewalDue, unlocks } from '@threadcrumbs/common/license'
+import { cloudUrl, licenseStore, trustedKeys } from '@threadcrumbs/common/license/store'
+import { ENTITLEMENT, PRO_FEATURES, devEntitlements } from '../src/tiers.js'
+
+const RENEW_RETRY_MS = 60 * 60 * 1000
+const TIMEOUT_MS = 15000
+const KEY_LIMIT = 200
+
+const CLOUD_ERRORS = {
+  bad_request: "That doesn't look like a license key.",
+  key_not_valid: "Polar doesn't recognize that key. Copy the whole key from your receipt. It starts with THREADCRUMBS-.",
+  device_limit: 'That key is already on as many computers as it allows. Remove one in your Polar customer portal, then try again.',
+  polar_unavailable: "Polar didn't answer. Try again in a minute.",
+}
+
+export function entitlementsFor(license, at, proFeatures = PRO_FEATURES) {
+  const features = Object.fromEntries(
+    Object.entries(proFeatures).map(([key, feature]) => [key, Boolean(license) && unlocks(license, ENTITLEMENT, feature.releasedAt, at)]),
+  )
+  return { pro: Boolean(license) && paidThrough(license, ENTITLEMENT, at) >= at, features }
+}
+
+function summary(license, at) {
+  if (!license) return null
+  return {
+    paidThrough: paidThrough(license, ENTITLEMENT, at) || null,
+    renewed: license.iat,
+    expires: license.exp,
+    entitlements: Object.keys(license.ent),
+  }
+}
+
+export function createLicensing({
+  development = false,
+  env = process.env,
+  store = licenseStore({ keys: trustedKeys({ env, development }) }),
+  cloud = cloudUrl({ env, development }),
+  fetch = globalThis.fetch,
+  clock = Date.now,
+} = {}) {
+  let renewing = null
+  let triedAt = -Infinity
+
+  async function post(path, body) {
+    const res = await fetch(`${cloud}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+    return { status: res.status, data: await res.json().catch(() => ({})) }
+  }
+
+  function renewIfDue({ license, token, at }) {
+    if (!cloud || !license || renewing || !renewalDue(license, at) || clock() - triedAt < RENEW_RETRY_MS) return
+    triedAt = clock()
+    renewing = post('/v1/license/renew', { license: token })
+      .then(({ status, data }) => (status === 200 && typeof data.license === 'string' ? store.save(data.license) : null))
+      .catch(() => null)
+      .finally(() => {
+        renewing = null
+      })
+  }
+
+  async function entitlements() {
+    const now = await store.current()
+    renewIfDue(now)
+    const open = development ? devEntitlements() : entitlementsFor(now.license, now.at)
+    return { ...open, license: summary(now.license, now.at), activation: Boolean(cloud) }
+  }
+
+  async function activate(key) {
+    const trimmed = typeof key === 'string' ? key.trim() : ''
+    if (!trimmed || trimmed.length > KEY_LIMIT) return { ok: false, error: CLOUD_ERRORS.bad_request }
+    if (!cloud) return { ok: false, error: "This copy of Threadgauge can't activate a license yet." }
+    let reply
+    try {
+      reply = await post('/v1/license', { key: trimmed, device: await store.device() })
+    } catch (err) {
+      return { ok: false, error: `Couldn't reach the license service: ${err.message}` }
+    }
+    const { status, data } = reply
+    if (status !== 200 || typeof data.license !== 'string') {
+      return { ok: false, error: CLOUD_ERRORS[data.error] || data.message || `The license service answered ${status}` }
+    }
+    const saved = await store.save(data.license)
+    if (!saved.ok) {
+      return { ok: false, error: saved.reason === 'unknown key' ? "That license was signed by a key this copy of Threadgauge doesn't trust." : "That license didn't check out." }
+    }
+    const result = await entitlements()
+    const covered = Boolean(result.license?.entitlements.includes(ENTITLEMENT))
+    return { ok: true, entitlements: result, note: covered ? null : "That key is on for this computer, but its plan doesn't include Threadgauge Pro. You can switch plans in your Polar customer portal and keep the same key." }
+  }
+
+  async function idle() {
+    await renewing
+  }
+
+  return { entitlements, activate, idle }
+}

package/server/monitor.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs'
+import { organizationReader } from '@threadcrumbs/common/orgs'
+import { TELEMETRY } from '@threadcrumbs/common/telemetry'
+
+const SETTLE_MS = 250
+const HEARTBEAT_MS = 5000
+
+export function createMonitor({ harnesses = TELEMETRY, settleMs = SETTLE_MS, heartbeatMs = HEARTBEAT_MS, organizations = organizationReader() } = {}) {
+  const listeners = new Set()
+  const watched = new Map()
+  let sessions = new Map()
+  let harnessStatus = []
+  let scannedAt = 0
+  let ready = null
+  let running = null
+  let rescan = false
+  let settleTimer = null
+  let heartbeat = null
+  let scannedOnce
+  const firstScan = new Promise((resolve) => (scannedOnce = resolve))
+
+  async function scanOnce() {
+    const found = []
+    const status = []
+    for (const harness of harnesses) {
+      let detected = false
+      let error = ''
+      try {
+        detected = Boolean(await harness.detect())
+        if (detected) found.push(...(await harness.scanSessions()))
+      } catch (err) {
+        error = String(err?.message || err)
+      }
+      status.push({ id: harness.id, name: harness.name, detected, error })
+    }
+    const tagged = await organizations(found).catch(() => found)
+    const next = new Map(tagged.map((session) => [session.id, { session, json: JSON.stringify(session) }]))
+
+    const upserts = [...next.values()].filter((e) => sessions.get(e.session.id)?.json !== e.json).map((e) => e.session)
+    const removed = [...sessions.keys()].filter((id) => !next.has(id))
+    const harnessesChanged = JSON.stringify(status) !== JSON.stringify(harnessStatus)
+    sessions = next
+    harnessStatus = status
+    scannedAt = Date.now()
+    watchRoots()
+
+    if (!upserts.length && !removed.length && !harnessesChanged) return
+    const update = { upserts, removed, scannedAt }
+    if (harnessesChanged) update.harnesses = status
+    for (const listener of listeners) listener(update)
+  }
+
+  function scan() {
+    if (running) {
+      rescan = true
+      return running
+    }
+    running = (async () => {
+      do {
+        rescan = false
+        try {
+          await scanOnce()
+        } finally {
+          scannedOnce()
+        }
+      } while (rescan)
+    })().finally(() => {
+      running = null
+    })
+    return running
+  }
+
+  function scheduleScan() {
+    if (settleTimer) return
+    settleTimer = setTimeout(() => {
+      settleTimer = null
+      scan()
+    }, settleMs)
+  }
+
+  function watchRoots() {
+    for (const harness of harnesses) {
+      for (const root of harness.watchRoots?.() || []) {
+        if (watched.has(root) || !fs.existsSync(root)) continue
+        try {
+          const watcher = fs.watch(root, { recursive: true, persistent: false }, scheduleScan)
+          watcher.on('error', () => {
+            watcher.close()
+            watched.delete(root)
+          })
+          watched.set(root, watcher)
+        } catch {}
+      }
+    }
+  }
+
+  return {
+    start() {
+      if (!ready) {
+        ready = Promise.race([scan(), firstScan])
+        heartbeat = setInterval(scan, heartbeatMs)
+        heartbeat.unref()
+      }
+      return ready
+    },
+    stop() {
+      clearInterval(heartbeat)
+      clearTimeout(settleTimer)
+      for (const watcher of watched.values()) watcher.close()
+      watched.clear()
+      listeners.clear()
+    },
+    scan,
+    async detail(id, options = {}) {
+      const entry = sessions.get(id)
+      if (!entry) {
+        const harness = harnesses.find((h) => String(id).startsWith(`${h.id}:`))
+        return harness?.readSession ? harness.readSession(id, options) : null
+      }
+      const harness = harnesses.find((h) => h.id === entry.session.harness)
+      const detail = harness?.sessionDetail ? await harness.sessionDetail(id, options) : null
+      return { session: entry.session, detail }
+    },
+    snapshot() {
+      return {
+        sessions: [...sessions.values()].map((e) => e.session),
+        harnesses: harnessStatus,
+        scannedAt,
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}

package/server/open.mjs

@@ -0,0 +1,49 @@
+import path from 'node:path'
+import { harnessById } from '@threadcrumbs/common/harnesses'
+import { present } from '@threadcrumbs/common/launch'
+import { createThreadCache } from './threads.mjs'
+const PLAIN_ARG = /^[\w@%+=:,./\\-]+$/
+
+const quoteFor = (windows) => (arg) => {
+  const value = String(arg)
+  if (PLAIN_ARG.test(value)) return value
+  return windows ? `'${value.replace(/['\u2018\u2019\u201A\u201B]/g, (q) => q + q)}'` : `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+export function commandLine({ argv, cwd }, { platform = process.platform } = {}) {
+  if (!Array.isArray(argv) || !argv.length) return null
+  const windows = platform === 'win32'
+  const quote = quoteFor(windows)
+  const bin = (windows ? path.win32 : path.posix).basename(String(argv[0])).replace(/\.(exe|cmd|bat|ps1)$/i, '')
+  const run = [bin, ...argv.slice(1)].map(quote).join(' ')
+  if (!cwd) return run
+  return windows ? `cd ${quote(cwd)}; ${run}` : `cd ${quote(cwd)} && ${run}`
+}
+
+export function createOpener({ harnessOf = harnessById, show = present, now = Date.now, platform = process.platform, threadsOf = createThreadCache({ now }) } = {}) {
+  async function lookUp(session) {
+    const harness = harnessOf(session.harness)
+    if (!harness?.openThread) return { harness: null, thread: null, ref: null }
+    let thread = (await threadsOf(harness, false)).find((t) => t.id === session.id)
+    if (!thread) thread = (await threadsOf(harness, true)).find((t) => t.id === session.id)
+    const native = session.id.slice(session.id.indexOf(':') + 1)
+    const ref = thread?.ref || { sessionId: native, cliSessionId: native, cwd: session.cwd || '' }
+    return { harness, thread, ref }
+  }
+
+  async function openSession(session, via = 'app') {
+    const { harness, thread, ref } = await lookUp(session)
+    if (!harness) return { ok: false, error: `Threadgauge can't open ${session.harness} threads` }
+    if (thread?.canOpen === false) return { ok: false, error: 'That thread has nothing its harness can open' }
+    return show(await harness.openThread(ref), via)
+  }
+
+  openSession.resume = async function resume(session) {
+    const { harness, thread, ref } = await lookUp(session)
+    if (!harness || thread?.canOpen === false) return null
+    const result = await harness.openThread(ref).catch(() => null)
+    return result?.command ? commandLine({ argv: result.command.argv, cwd: result.command.cwd || session.cwd }, { platform }) : null
+  }
+
+  return openSession
+}

package/server/paths.mjs

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { launch } from '@threadcrumbs/common/launch'
+
+export const EDITORS = {
+  vscode: { name: 'VS Code', scheme: 'vscode' },
+  cursor: { name: 'Cursor', scheme: 'cursor' },
+  windsurf: { name: 'Windsurf', scheme: 'windsurf' },
+  zed: { name: 'Zed', scheme: 'zed' },
+  system: { name: 'the default app', scheme: null },
+}
+
+const keyOf = (file, platform) => (platform === 'win32' ? file.toLowerCase() : file)
+
+const WINDOWS_RUNNABLE = new Set([
+  '.exe', '.com', '.bat', '.cmd', '.scr', '.pif', '.cpl', '.msc', '.dll', '.sys',
+  '.js', '.jse', '.vbs', '.vbe', '.wsf', '.wsh', '.wsc', '.sct',
+  '.hta', '.chm',
+  '.ps1', '.psm1', '.psd1', '.ps1xml', '.psc1', '.pssc', '.cdxml',
+  '.py', '.pyw', '.pyz', '.pyzw', '.pyc', '.pyo',
+  '.lnk', '.url', '.scf', '.library-ms', '.searchconnector-ms', '.settingcontent-ms',
+  '.msi', '.msp', '.mst', '.msix', '.msixbundle', '.appx', '.appxbundle', '.appinstaller', '.application',
+  '.reg', '.inf', '.jar', '.gadget', '.diagcab', '.xll', '.website',
+])
+const MAC_RUNNABLE = new Set(['.app', '.command', '.tool', '.terminal', '.workflow', '.action', '.pkg', '.mpkg', '.jar', '.fileloc'])
+
+export function runsWhenOpened(file, { platform = process.platform, pathext = process.env.PATHEXT } = {}) {
+  if (platform === 'win32') {
+    const name = file.replace(/[. ]+$/, '')
+    if (name.lastIndexOf(':') > 1) return true
+    const ext = path.extname(name).toLowerCase()
+    const listed = (pathext || '').toLowerCase().split(';').filter(Boolean)
+    return WINDOWS_RUNNABLE.has(ext) || listed.includes(ext)
+  }
+  if (platform === 'darwin') return MAC_RUNNABLE.has(path.extname(file).toLowerCase())
+  return false
+}
+
+export const REVEALERS = { win32: 'File Explorer', darwin: 'Finder' }
+
+export function revealFile(file, { platform = process.platform, run = spawn, open = launch } = {}) {
+  const [cmd, args, options] =
+    platform === 'win32'
+      ? ['explorer.exe', [`/select,"${file}"`], { windowsVerbatimArguments: true }]
+      : platform === 'darwin'
+        ? ['open', ['-R', file], {}]
+        : [null]
+  if (!cmd) return open(path.dirname(file))
+  const child = run(cmd, args, { ...options, stdio: 'ignore', detached: true })
+  child.on?.('error', () => {})
+  child.unref?.()
+}
+
+export function editorUrl(editor, file, line = null, { platform = process.platform } = {}) {
+  const scheme = EDITORS[editor]?.scheme
+  if (!scheme) return file
+  const forward = platform === 'win32' ? file.replace(/\\/g, '/') : file
+  const encoded = encodeURI(forward).replace(/#/g, '%23').replace(/\?/g, '%3F')
+  const at = Number.isInteger(line) && line > 0 ? `:${line}` : ''
+  return `${scheme}://file${encoded.startsWith('/') ? '' : '/'}${encoded}${at}`
+}
+
+export function touchedPaths(session, detail, { platform = process.platform } = {}) {
+  const base = session.cwd || session.projectPath || ''
+  const allowed = new Map()
+  const add = (file, kind) => {
+    if (!file || !base) return
+    const full = path.resolve(base, file)
+    if (!allowed.has(keyOf(full, platform))) allowed.set(keyOf(full, platform), { full, kind })
+  }
+  add(session.cwd, 'folder')
+  add(session.projectPath, 'folder')
+  add(detail?.source, 'file')
+  for (const file of detail?.files || []) add(file.path, 'file')
+  for (const call of detail?.activity || []) add(call.path, 'file')
+  for (const part of detail?.contextBreakdown?.parts || []) {
+    if (part.id === 'memory') for (const item of part.items || []) if (/\.md$/i.test(item.path || '')) add(item.path, 'file')
+  }
+  return { base, allowed }
+}
+
+export function createPathOpener({ open = launch, reveal = (file) => revealFile(file, { platform }), stat = fsp.stat, platform = process.platform, pathext = process.env.PATHEXT } = {}) {
+  return async function openPath({ session, detail, path: wanted, line = null, editor = 'vscode' }) {
+    const { base, allowed } = touchedPaths(session, detail, { platform })
+    if (!base) return { ok: false, status: 404, error: "Threadgauge doesn't know this thread's folder" }
+    const full = path.resolve(base, typeof wanted === 'string' && wanted ? wanted : base)
+    const entry = allowed.get(keyOf(full, platform))
+    if (!entry) return { ok: false, status: 403, error: "Threadgauge only opens files and folders this thread touched" }
+    const found = await stat(entry.full).catch(() => null)
+    if (!found) return { ok: false, status: 404, error: `${path.basename(entry.full)} isn't there anymore` }
+    if (found.isDirectory()) {
+      open(entry.full)
+      return { ok: true, kind: 'folder', path: entry.full }
+    }
+    const chosen = editor in EDITORS ? editor : 'vscode'
+    if (chosen === 'system' && runsWhenOpened(entry.full, { platform, pathext })) {
+      reveal(entry.full)
+      return { ok: true, kind: 'file', path: entry.full, editor: REVEALERS[platform] || 'the file manager', revealed: true }
+    }
+    open(editorUrl(chosen, entry.full, Number.isInteger(line) ? line : null, { platform }))
+    return { ok: true, kind: 'file', path: entry.full, editor: EDITORS[chosen].name }
+  }
+}

package/server/serve.mjs

@@ -0,0 +1,8 @@
+import { startServer } from './http-server.mjs'
+import { DEFAULT_PORT } from './lib/ports.mjs'
+
+const PORT = Number(process.env.PORT) || DEFAULT_PORT
+const HOST = process.env.THREADGAUGE_HOST || '127.0.0.1'
+
+await startServer({ port: PORT, host: HOST })
+console.log(`Threadgauge → http://${HOST}:${PORT}`)

package/server/threadnauts.mjs

@@ -0,0 +1,23 @@
+const FIRST_PORT = 5274
+const PORTS_TO_TRY = 20
+const LOOPBACKS = ['127.0.0.1', '::1']
+const PROBE_TIMEOUT_MS = 500
+
+const originOf = (host, port) => `http://${host.includes(':') ? `[${host}]` : host}:${port}`
+
+async function answersAsThreadnauts(origin, fetch) {
+  try {
+    const response = await fetch(`${origin}/api/about`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+    return (await response.json())?.app === 'threadnauts'
+  } catch {
+    return false
+  }
+}
+
+export async function findThreadnauts({ fetch = globalThis.fetch, first = FIRST_PORT, tries = PORTS_TO_TRY, hosts = LOOPBACKS } = {}) {
+  const probes = []
+  for (let port = first; port < first + tries; port++) for (const host of hosts) probes.push({ port, origin: originOf(host, port) })
+  const found = await Promise.all(probes.map(({ origin }) => answersAsThreadnauts(origin, fetch)))
+  const index = found.indexOf(true)
+  return index === -1 ? null : `http://localhost:${probes[index].port}/`
+}

package/server/threads.mjs

@@ -0,0 +1,12 @@
+const THREADS_TTL_MS = 30_000
+
+export function createThreadCache({ now = Date.now, ttl = THREADS_TTL_MS } = {}) {
+  const threads = new Map()
+  return async function threadsOf(harness, fresh = false) {
+    const hit = threads.get(harness.id)
+    if (!fresh && hit && now() - hit.at < ttl) return hit.list
+    const list = await harness.scanThreads().catch(() => [])
+    threads.set(harness.id, { at: now(), list })
+    return list
+  }
+}

package/src/tiers.js

@@ -0,0 +1,20 @@
+export const ENTITLEMENT = 'threadgauge.pro'
+
+export const UPGRADE_URL = 'https://threadgauge.io/pro'
+
+export const released = (year, month, day) => Date.UTC(year, month - 1, day) / 1000
+
+// Anything Threadgauge reads from this machine without acting is free, older threads included
+// (2026-11-08), so no feature is Pro yet. Threadbare's controls are listed here when they ship,
+// each as { releasedAt: released(year, month, day), title, text }.
+export const PRO_FEATURES = {}
+
+function every(open) {
+  return Object.fromEntries(Object.keys(PRO_FEATURES).map((key) => [key, open]))
+}
+
+export const freeEntitlements = () => ({ pro: false, features: every(false) })
+
+export const devEntitlements = () => ({ pro: true, features: every(true) })
+
+export const featureOpen = (entitlements, feature) => entitlements?.features?.[feature] === true