mango-cms 0.3.34 → 0.3.35

package/lib/vibe-orchestrator/src/sessionManager.js

@@ -0,0 +1,291 @@
+// sessionManager.js
+//
+// Per-site session registry. One logical session per site survives across
+// prompts: we remember the last claude session_id so the next prompt resumes
+// the same conversation (`claude --resume <id>`), and we carry cumulative token
+// usage forward so the per-session cap spans the whole conversation, not a
+// single turn. Only one run may be in-flight per site at a time.
+
+import { EventEmitter } from 'node:events'
+import { runPrompt } from './claudeRunner.js'
+import { resolveSiteDir, config, canRunLive } from './config.js'
+import { composePrompt } from './preamble.js'
+import { persistScreenshot } from './screenshot.js'
+import { persistAttachments } from './attachments.js'
+import { appendCost } from './costStore.js'
+import { mirrorCost } from './costMirror.js'
+import { autoCommit } from './recovery.js'
+
+class SessionManager {
+  /** @param {object} [deps] - injectable runPrompt / clock / reaper for tests */
+  constructor(deps = {}) {
+    this.runPrompt = deps.runPrompt || runPrompt
+    this.cfg = deps.config || config
+    this.now = deps.now || (() => Date.now())
+    // HAP-1123: per-turn cost persistence. recordCost writes the durable NDJSON
+    // log (system of record); mirrorCost best-effort POSTs the same record to the
+    // Mango `vibeCosts` collection. Both injectable so tests stay fs/network-free.
+    this.recordCost = deps.recordCost || appendCost
+    this.mirrorCost = deps.mirrorCost || mirrorCost
+    // HAP-1124: after each run, auto-commit the applied edit to the clone's git so
+    // there is always a way back. Injectable so tests stay git-free.
+    this.autoCommit = deps.autoCommit || autoCommit
+    /** @type {Map<string, object>} site -> session record */
+    this.sessions = new Map()
+    this._reaper = null
+    // Auto-start the idle reaper unless explicitly disabled (tests pass false).
+    if (deps.startReaper !== false && this.cfg.sessionIdleMs > 0) this.startReaper()
+  }
+
+  _ensure(site) {
+    let s = this.sessions.get(site)
+    if (!s) {
+      s = {
+        site,
+        sessionId: null,
+        cumulativeTokens: 0,
+        status: 'idle', // idle | running | error
+        active: null,    // current run handle while running
+        lastResult: null,
+        promptCount: 0,
+        lastActivity: this.now(), // ms; bumped by prompts, events, and keepalive touches
+        readers: 0,               // open SSE connections actively reading this session
+      }
+      this.sessions.set(site, s)
+    }
+    return s
+  }
+
+  get(site) {
+    return this.sessions.get(site) || null
+  }
+
+  list() {
+    return [...this.sessions.values()].map((s) => ({
+      site: s.site,
+      sessionId: s.sessionId,
+      cumulativeTokens: s.cumulativeTokens,
+      status: s.status,
+      promptCount: s.promptCount,
+    }))
+  }
+
+  /** Reset a site's conversation (next prompt starts fresh). */
+  reset(site) {
+    const s = this.sessions.get(site)
+    if (s && s.status === 'running') throw new Error('cannot reset while running')
+    this.sessions.delete(site)
+  }
+
+  /**
+   * Submit a prompt to a site. Returns the run's EventEmitter immediately;
+   * progress events flow through it, and the session record is updated on end.
+   *
+   * @param {string} site
+   * @param {string} prompt
+   * @param {object} [opts]
+   * @param {object} [opts.pageContext] - per-turn snapshot of what the owner sees
+   * @param {Array}  [opts.attachments] - { name, mime, dataUrl } files to persist
+   * @returns {{ emitter: EventEmitter, done: Promise<object>, abort: ()=>void }}
+   */
+  submit(site, prompt, opts = {}) {
+    if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+      throw new Error('prompt is required')
+    }
+    if (!canRunLive()) {
+      throw new Error('CLAUDE_CODE_OAUTH_TOKEN not set — cannot run live')
+    }
+    const cwd = resolveSiteDir(site) // throws on bad slug / not allowed
+    const s = this._ensure(site)
+    if (s.status === 'running') {
+      throw new Error(`site ${site} already has a run in progress`)
+    }
+
+    // Remaining budget for this conversation (cap spans all turns).
+    const remaining = this.cfg.tokenCap > 0
+      ? Math.max(0, this.cfg.tokenCap - s.cumulativeTokens)
+      : 0
+    if (this.cfg.tokenCap > 0 && remaining === 0) {
+      throw new Error(`session token cap (${this.cfg.tokenCap}) reached for ${site}`)
+    }
+
+    // HAP-1111: enrich the prompt with agent orientation (first turn only) and a
+    // per-turn snapshot of what the owner is looking at, including a screenshot
+    // the agent can Read. Resumed turns already carry the orientation in history.
+    const ctx = { ...(opts.pageContext || {}) }
+    if (ctx.screenshot) {
+      const shot = persistScreenshot(site, ctx.screenshot)
+      delete ctx.screenshot
+      if (shot) ctx.screenshotPath = shot
+    }
+    // HAP-1126: persist any pasted/uploaded files (images + PDFs) to temp paths
+    // the agent can Read, and hand the absolute paths to the preamble. Passing an
+    // array (even empty) sweeps the previous turn's files so temp stays bounded.
+    const savedAttachments = persistAttachments(site, opts.attachments)
+    if (savedAttachments.length) {
+      ctx.attachmentPaths = savedAttachments.map((a) => ({ name: a.name, path: a.path }))
+    }
+    const composedPrompt = composePrompt({
+      prompt,
+      pageContext: ctx,
+      includePreamble: !s.sessionId,
+    })
+
+    // HAP-1123: remember a short, single-line prompt summary and the page the
+    // owner was on so the persisted cost record is human-readable on an invoice.
+    const promptSummary = prompt.trim().replace(/\s+/g, ' ').slice(0, 140)
+    const pagePath = ctx.route || ctx.url || null
+
+    const handle = this.runPrompt({
+      prompt: composedPrompt,
+      cwd,
+      oauthToken: this.cfg.oauthToken,
+      claudeBin: this.cfg.claudeBin,
+      permissionMode: this.cfg.permissionMode,
+      model: this.cfg.model,
+      resumeSessionId: s.sessionId,
+      tokenCap: remaining,
+      timeoutMs: this.cfg.runTimeoutMs,
+      markupPct: this.cfg.markupPct,
+      // HAP-1124: install the server-side PreToolUse path guard for this run.
+      pathGuardHook: this.cfg.pathGuardEnabled ? this.cfg.pathGuardHook : '',
+      // HAP-1096: pre-approve read-only web tools + grant read access to the temp
+      // dir holding the viewport screenshot and any pasted/uploaded attachments.
+      allowedTools: this.cfg.allowedTools,
+      addDirs: this.cfg.toolExtraDirs,
+    })
+
+    s.status = 'running'
+    s.active = handle
+    s.promptCount += 1
+    s.lastActivity = this.now()
+
+    // Every streamed event is fresh activity — keep the session warm while it runs.
+    if (handle.emitter?.on) handle.emitter.on('event', () => { s.lastActivity = this.now() })
+
+    handle.done.then((summary) => {
+      if (summary.sessionId) s.sessionId = summary.sessionId
+      // Accumulate BILLABLE tokens (new input + output), not the full volume that
+      // re-counts cached context each turn — keeps the per-session cap meaningful
+      // across multiple prompts. Falls back to totalTokens for older summaries.
+      if (summary.tokens) {
+        s.cumulativeTokens += summary.tokens.billableTokens ?? summary.tokens.totalTokens
+      }
+      s.status = summary.ok ? 'idle' : 'error'
+      s.active = null
+      s.lastResult = summary
+      s.lastActivity = this.now()
+
+      // Persist a per-turn cost record (HAP-1123). Best-effort: a logging failure
+      // must never surface to the run, and the Mango mirror is fire-and-forget.
+      try {
+        const tk = summary.tokens || {}
+        const entry = {
+          ts: this.now(),
+          site,
+          path: pagePath,
+          sessionId: summary.sessionId || s.sessionId || null,
+          model: summary.model || this.cfg.model || null,
+          costUsd: typeof summary.costUsd === 'number' ? summary.costUsd : null,
+          tokens: {
+            input: tk.inputTokens,
+            output: tk.outputTokens,
+            cacheRead: tk.cacheReadTokens,
+            total: tk.totalTokens,
+            billable: tk.billableTokens,
+          },
+          promptSummary,
+          ok: !!summary.ok,
+        }
+        const saved = this.recordCost(entry)
+        Promise.resolve(this.mirrorCost(saved)).catch(() => {})
+      } catch { /* cost logging is never allowed to break a run */ }
+
+      // HAP-1124: auto-commit any applied edit so history always exists and the
+      // tree is never left non-recoverable. Runs even on a non-ok/aborted summary
+      // (a partial edit must still be captured). Best-effort + injectable: a git
+      // failure must never surface to the run.
+      if (this.cfg.autoCommitEnabled !== false) {
+        Promise.resolve()
+          .then(() => this.autoCommit(site, {
+            summary: promptSummary,
+            sessionId: summary.sessionId || s.sessionId || null,
+          }))
+          .catch(() => {})
+      }
+    }).catch(() => {
+      s.status = 'error'
+      s.active = null
+      s.lastActivity = this.now()
+    })
+
+    return handle
+  }
+
+  /** Abort the in-flight run for a site, if any. */
+  abort(site) {
+    const s = this.sessions.get(site)
+    if (s?.active) s.active.abort()
+  }
+
+  /**
+   * Mark a session as freshly active without sending a prompt. Called on the SSE
+   * keepalive ping so a session that is being actively read (but not prompted) is
+   * not reaped mid-read — the original idle-reaper bug (HAP-1110 item 4): the old
+   * code only updated activity on a new message, so the keepalive did not count.
+   */
+  touch(site) {
+    const s = this.sessions.get(site)
+    if (s) s.lastActivity = this.now()
+  }
+
+  /** Register an open SSE reader for a site; a session with readers is never reaped. */
+  addReader(site) {
+    const s = this._ensure(site)
+    s.readers += 1
+    s.lastActivity = this.now()
+  }
+
+  /** Release an SSE reader and record the disconnect time as activity. */
+  removeReader(site) {
+    const s = this.sessions.get(site)
+    if (!s) return
+    s.readers = Math.max(0, s.readers - 1)
+    s.lastActivity = this.now()
+  }
+
+  /**
+   * Reap idle sessions. A session is reaped only when it is NOT running, has NO
+   * open readers, and has been quiet longer than the idle TTL. Running sessions
+   * and actively-read sessions are always kept warm.
+   * @returns {string[]} the sites that were reaped
+   */
+  reap() {
+    const ttl = this.cfg.sessionIdleMs
+    if (!ttl || ttl <= 0) return []
+    const now = this.now()
+    const reaped = []
+    for (const [site, s] of this.sessions) {
+      if (s.status === 'running' || s.readers > 0) continue
+      if (now - s.lastActivity > ttl) {
+        this.sessions.delete(site)
+        reaped.push(site)
+      }
+    }
+    return reaped
+  }
+
+  /** Start the periodic idle reaper (no-op if already running). */
+  startReaper() {
+    if (this._reaper) return
+    this._reaper = setInterval(() => this.reap(), this.cfg.reaperIntervalMs)
+    if (this._reaper.unref) this._reaper.unref() // never keep the process alive
+  }
+
+  /** Stop the idle reaper. */
+  stopReaper() {
+    if (this._reaper) { clearInterval(this._reaper); this._reaper = null }
+  }
+}
+
+export { SessionManager }

package/lib/vibe-orchestrator/src/streamParser.js

@@ -0,0 +1,188 @@
+// streamParser.js
+//
+// Parses Claude Code headless `--output-format stream-json` output into a
+// normalized stream of progress events the front-end can render.
+//
+// Claude Code emits newline-delimited JSON (NDJSON). stdout chunks can split a
+// line anywhere, so we buffer until we see a newline. Each complete line is one
+// JSON object; we normalize the shapes we care about and pass everything else
+// through as `unknown` so nothing is silently dropped.
+//
+// Known top-level message types (Claude Code v2.x):
+//   { type: "system", subtype: "init", session_id, model, tools, cwd, ... }
+//   { type: "assistant", message: { content: [...], usage: {...} }, session_id }
+//   { type: "user",      message: { content: [tool_result ...] }, session_id }
+//   { type: "result",    subtype, total_cost_usd, duration_ms, usage, result, session_id }
+//
+// Pure module: no I/O, no process access. Fully unit-testable without a token.
+
+/**
+ * @typedef {Object} ProgressEvent
+ * @property {string} kind   - normalized event kind (see below)
+ * @property {number} [ts]   - caller-supplied timestamp (parser never reads the clock)
+ */
+
+const KINDS = Object.freeze({
+  SESSION_START: 'session_start',
+  ASSISTANT_TEXT: 'assistant_text',
+  THINKING: 'thinking',
+  TOOL_USE: 'tool_use',
+  TOOL_RESULT: 'tool_result',
+  RESULT: 'result',
+  PARSE_ERROR: 'parse_error',
+  UNKNOWN: 'unknown',
+})
+
+/** Pull a normalized usage object out of whatever shape it arrives in. */
+function normalizeUsage(usage) {
+  if (!usage || typeof usage !== 'object') return null
+  const freshInput = usage.input_tokens || 0
+  const cacheCreation = usage.cache_creation_input_tokens || 0
+  const cacheRead = usage.cache_read_input_tokens || 0
+  const input = freshInput + cacheCreation + cacheRead
+  const output = usage.output_tokens || 0
+  return {
+    inputTokens: input,            // total input incl. cached context (display)
+    outputTokens: output,
+    cacheReadTokens: cacheRead,
+    totalTokens: input + output,   // full token volume (display)
+    // What actually counts against the per-session cap: NEW tokens only. The
+    // cached context (cache_read) is re-reported on every turn and is cheap
+    // already-paid context — summing it across turns balloons the count and
+    // would trip the cap on a trivial multi-turn edit. Exclude it.
+    billableTokens: freshInput + cacheCreation + output,
+    raw: usage,
+  }
+}
+
+/** Normalize a single already-parsed NDJSON object into 0+ progress events. */
+function normalizeMessage(msg) {
+  if (!msg || typeof msg !== 'object') {
+    return [{ kind: KINDS.UNKNOWN, raw: msg }]
+  }
+
+  switch (msg.type) {
+    case 'system':
+      if (msg.subtype === 'init') {
+        return [{
+          kind: KINDS.SESSION_START,
+          sessionId: msg.session_id || null,
+          model: msg.model || null,
+          tools: Array.isArray(msg.tools) ? msg.tools : [],
+          cwd: msg.cwd || null,
+        }]
+      }
+      return [{ kind: KINDS.UNKNOWN, raw: msg }]
+
+    case 'assistant': {
+      const content = msg.message?.content
+      const usage = normalizeUsage(msg.message?.usage)
+      const events = []
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text' && block.text) {
+            events.push({ kind: KINDS.ASSISTANT_TEXT, text: block.text })
+          } else if (block.type === 'thinking' && block.thinking) {
+            events.push({ kind: KINDS.THINKING, text: block.thinking })
+          } else if (block.type === 'tool_use') {
+            events.push({
+              kind: KINDS.TOOL_USE,
+              tool: block.name,
+              toolId: block.id,
+              input: block.input,
+            })
+          }
+        }
+      }
+      // An assistant turn with usage but no renderable block still carries token
+      // accounting we must not lose — emit a bare usage-only event.
+      if (events.length === 0 && usage) {
+        events.push({ kind: KINDS.ASSISTANT_TEXT, text: '' })
+      }
+      // One assistant message == one model API call == one usage report. Attach
+      // usage to the FIRST event only so the token meter counts it once per turn,
+      // not once per content block (a turn may carry text + tool_use together).
+      if (events.length && usage) events[0].usage = usage
+      return events
+    }
+
+    case 'user': {
+      const content = msg.message?.content
+      const events = []
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'tool_result') {
+            events.push({
+              kind: KINDS.TOOL_RESULT,
+              toolId: block.tool_use_id,
+              isError: !!block.is_error,
+              content: block.content,
+            })
+          }
+        }
+      }
+      return events.length ? events : [{ kind: KINDS.UNKNOWN, raw: msg }]
+    }
+
+    case 'result':
+      return [{
+        kind: KINDS.RESULT,
+        subtype: msg.subtype || null,
+        isError: !!msg.is_error,
+        durationMs: msg.duration_ms ?? null,
+        costUsd: msg.total_cost_usd ?? null,
+        usage: normalizeUsage(msg.usage),
+        numTurns: msg.num_turns ?? null,
+        sessionId: msg.session_id || null,
+        result: typeof msg.result === 'string' ? msg.result : null,
+      }]
+
+    default:
+      return [{ kind: KINDS.UNKNOWN, raw: msg }]
+  }
+}
+
+/**
+ * Stateful NDJSON line buffer. Feed it raw stdout chunks; it returns the
+ * normalized progress events for every *complete* line seen so far.
+ */
+class StreamParser {
+  constructor() {
+    this.buffer = ''
+  }
+
+  /**
+   * @param {string|Buffer} chunk
+   * @returns {ProgressEvent[]}
+   */
+  push(chunk) {
+    this.buffer += chunk.toString()
+    const events = []
+    let nl
+    while ((nl = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, nl).trim()
+      this.buffer = this.buffer.slice(nl + 1)
+      if (line) events.push(...this._parseLine(line))
+    }
+    return events
+  }
+
+  /** Flush any trailing partial line at stream end. */
+  flush() {
+    const line = this.buffer.trim()
+    this.buffer = ''
+    return line ? this._parseLine(line) : []
+  }
+
+  _parseLine(line) {
+    let parsed
+    try {
+      parsed = JSON.parse(line)
+    } catch {
+      return [{ kind: KINDS.PARSE_ERROR, raw: line }]
+    }
+    return normalizeMessage(parsed)
+  }
+}
+
+export { StreamParser, normalizeMessage, normalizeUsage, KINDS }

package/lib/vibe-orchestrator/src/tokenMeter.js

@@ -0,0 +1,64 @@
+// tokenMeter.js
+//
+// Cumulative token accounting + per-session cap. Fed the `usage` objects that
+// streamParser attaches to assistant events. Pure/in-memory: one instance per
+// session.
+//
+// The cap counts BILLABLE tokens (new input + cache creation + output), NOT the
+// full `totalTokens` — Claude Code re-reports the whole cached context
+// (cache_read) on every turn, so summing totals across turns balloons the count
+// and would trip the cap on a trivial multi-turn edit. We still track the full
+// volume for display.
+
+class TokenMeter {
+  /** @param {number} cap - max cumulative BILLABLE tokens before tripping (0 = unlimited) */
+  constructor(cap = 0) {
+    this.cap = cap > 0 ? cap : 0
+    this.inputTokens = 0      // full input incl. re-read cache (display)
+    this.outputTokens = 0
+    this.cacheReadTokens = 0  // re-read cached context (display / cost breakdown)
+    this.billableTokens = 0   // new input + cache creation + output (cap basis)
+  }
+
+  get totalTokens() {
+    return this.inputTokens + this.outputTokens
+  }
+
+  /**
+   * Record one assistant turn's usage. Returns true if the cap is now exceeded.
+   * Accepts the normalized usage from streamParser; falls back to totalTokens
+   * when billableTokens is absent (older callers / hand-built usage in tests).
+   * @param {{inputTokens?:number, outputTokens?:number, totalTokens?:number, billableTokens?:number}|null} usage
+   */
+  record(usage) {
+    if (!usage) return this.exceeded
+    this.inputTokens += usage.inputTokens || 0
+    this.outputTokens += usage.outputTokens || 0
+    this.cacheReadTokens += usage.cacheReadTokens || 0
+    const billable = usage.billableTokens != null
+      ? usage.billableTokens
+      : (usage.totalTokens != null
+        ? usage.totalTokens
+        : (usage.inputTokens || 0) + (usage.outputTokens || 0))
+    this.billableTokens += billable
+    return this.exceeded
+  }
+
+  get exceeded() {
+    return this.cap > 0 && this.billableTokens >= this.cap
+  }
+
+  snapshot() {
+    return {
+      inputTokens: this.inputTokens,
+      outputTokens: this.outputTokens,
+      cacheReadTokens: this.cacheReadTokens,
+      totalTokens: this.totalTokens,
+      billableTokens: this.billableTokens,
+      cap: this.cap,
+      exceeded: this.exceeded,
+    }
+  }
+}
+
+export { TokenMeter }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mango-cms",
-  "version": "0.3.34",
+  "version": "0.3.35",
   "type": "module",
   "main": "./index.js",
   "exports": {

package/readme.md

@@ -2,6 +2,12 @@
 
 Mango is a powerful, code-first CMS built on MongoDB that emphasizes configuration through code. This documentation covers how to configure and use Mango CMS through the `config` folder.
 
+> **Vibe (in-page AI coding):** to activate the optional ⌘K "edit your live site"
+> experience on a Mango project, follow [docs/VIBE_ACTIVATION.md](docs/VIBE_ACTIVATION.md)
+> — install/upgrade → flip `settings.vibe.enabled` → set `VITE_VIBE_SHELL` → run
+> the bundled orchestrator + gateway behind the infra templates in
+> [default/infra/vibe/](default/infra/vibe/). No source copying required.
+
 ## Table of Contents
 
 1. [Collections](#collections)