backeer-opencode 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.1.2 - 2026-09-01
+
+- Replace raw HTTP log lines with compact Backeer console status messages.
+- Add restrained TTY colors with `NO_COLOR` support.
+- Suppress repeated connection errors for 30 seconds.
+- Add `BACKEER_LOG_LEVEL` and the `logLevel` plugin option.
+- Keep technical HTTP and error details in debug mode only.
+
 ## 0.1.1 - 2026-09-01
 
 - Add `backeer-opencode configure` for hidden interactive token entry.

package/README.md

@@ -109,6 +109,7 @@ environment variables are supported:
 | `BACKEER_NOTIFY_PERMISSIONS` | Set to `false` to disable permission notifications and remote replies |
 | `BACKEER_NOTIFY_QUESTIONS` | Set to `false` to disable question notifications |
 | `BACKEER_NOTIFY_TODOS` | Set to `false` to disable todo-completion notifications |
+| `BACKEER_LOG_LEVEL` | `info` (default), `error`, `debug`, or `silent` |
 
 For npm installations, non-secret options can also be supplied through the
 OpenCode plugin tuple syntax:
@@ -128,8 +129,25 @@ OpenCode plugin tuple syntax:
 }
 ```
 
-Supported options are `origin`, `tokenFile`, `permissions`, `questions`, and
-`todos`. The token itself is deliberately not a plugin option.
+Supported options are `origin`, `tokenFile`, `permissions`, `questions`,
+`todos`, and `logLevel`. The token itself is deliberately not a plugin option.
+
+## Console feedback
+
+The plugin writes compact, single-line status messages instead of raw HTTP logs:
+
+```text
+◆ Backeer  Permission request sent
+◆ Backeer  Question sent
+◆ Backeer  Todo completion sent
+✓ Backeer  Decision applied: Always allow
+! Backeer  Connection interrupted — retrying
+```
+
+TTY output uses restrained status colors and respects `NO_COLOR`. Repeated
+connection errors are suppressed for 30 seconds. Normal `info` output omits HTTP
+status codes and internal errors; set `BACKEER_LOG_LEVEL=debug` when technical
+details are needed. Set it to `error` for failures only or `silent` for no output.
 
 ## Events and decisions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backeer-opencode",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Backeer notifications and remote permission decisions for OpenCode",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -8,6 +8,14 @@ const RETRY_DELAYS_MS = [0, 500, 1500]
 const MAX_COMPLETED_COMMANDS = 500
 const MAX_TRACKED_ITEMS = 500
 const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
+const DECISION_LABELS = {
+  once: "Allow once",
+  always: "Always allow",
+  reject: "Reject",
+}
+const LOG_LEVELS = new Set(["silent", "error", "info", "debug"])
+const LOG_RANK = { silent: 0, error: 1, info: 2, debug: 3 }
+const LOG_DEDUPLICATION_MS = 30_000
 
 class HttpError extends Error {
   constructor(message, status, responseBody = "") {
@@ -21,6 +29,61 @@ class HttpError extends Error {
 const limit = (value, length = 1000) =>
   String(value ?? "").slice(0, length)
 
+function normalizeLogLevel(value) {
+  const level = String(value ?? "info").trim().toLowerCase()
+  return LOG_LEVELS.has(level) ? level : "info"
+}
+
+function createConsoleReporter(levelValue) {
+  const level = normalizeLogLevel(levelValue)
+  const useColor = Boolean(process.stdout?.isTTY) &&
+    !("NO_COLOR" in process.env) && process.env.TERM !== "dumb"
+  const recentlyEmitted = new Map()
+
+  const decorate = (code, text) => useColor ? `\u001b[${code}m${text}\u001b[0m` : text
+  const symbols = {
+    info: decorate("36", "◆"),
+    success: decorate("32", "◆"),
+    applied: decorate("32", "✓"),
+    warning: decorate("33", "!"),
+    error: decorate("31", "×"),
+    debug: decorate("2", "·"),
+  }
+  const brand = decorate("1", "Backeer")
+
+  function emit(requiredLevel, kind, message, detail, deduplicate = false) {
+    if (LOG_RANK[level] < LOG_RANK[requiredLevel]) return
+
+    const key = `${kind}:${message}`
+    const now = Date.now()
+    if (deduplicate) {
+      const previous = recentlyEmitted.get(key)
+      if (previous && now - previous < LOG_DEDUPLICATION_MS) return
+      recentlyEmitted.delete(key)
+      recentlyEmitted.set(key, now)
+      while (recentlyEmitted.size > 100) {
+        recentlyEmitted.delete(recentlyEmitted.keys().next().value)
+      }
+    }
+
+    const technical = level === "debug" && detail
+      ? decorate("2", ` · ${limit(detail, 500)}`)
+      : ""
+    const line = `${symbols[kind]} ${brand}  ${message}${technical}`
+    if (kind === "error" || kind === "warning") console.error(line)
+    else console.log(line)
+  }
+
+  return {
+    info: (message, detail) => emit("info", "info", message, detail),
+    success: (message, detail) => emit("info", "success", message, detail),
+    applied: (message, detail) => emit("info", "applied", message, detail),
+    warning: (message, detail) => emit("error", "warning", message, detail, true),
+    error: (message, detail) => emit("error", "error", message, detail, true),
+    debug: (message, detail) => emit("debug", "debug", message, detail),
+  }
+}
+
 function defaultConfigDirectory() {
   const base = process.env.XDG_CONFIG_HOME?.trim()
   return base ? join(base, "opencode") : join(homedir(), ".config", "opencode")
@@ -69,6 +132,9 @@ function loadConfig(options = {}) {
       options.questions ?? process.env.BACKEER_NOTIFY_QUESTIONS,
     ),
     todos: enabled(options.todos ?? process.env.BACKEER_NOTIFY_TODOS),
+    logLevel: normalizeLogLevel(
+      options.logLevel ?? process.env.BACKEER_LOG_LEVEL,
+    ),
   }
 }
 
@@ -159,7 +225,7 @@ function permissionIdentity(request) {
   }
 }
 
-async function publishPermission(config, request, directory, identity) {
+async function publishPermission(config, reporter, request, directory, identity) {
   const permissionType = request.permission ?? request.action ?? "unknown"
   const resources = Array.isArray(request.patterns)
     ? request.patterns.join(", ")
@@ -190,7 +256,7 @@ async function publishPermission(config, request, directory, identity) {
     notify: true,
     direction: "in",
   })
-  console.log(`[backeer] permission event accepted (${result.status})`)
+  reporter.success("Permission request sent", `HTTP ${result.status}`)
 }
 
 function questionIdentity(request) {
@@ -219,7 +285,7 @@ function formatQuestionOptions(options) {
     .join(" | ")
 }
 
-async function resolveSessionTitle(client, directory, sessionID) {
+async function resolveSessionTitle(client, directory, sessionID, reporter) {
   if (typeof client?.session?.get !== "function") return ""
 
   try {
@@ -230,12 +296,19 @@ async function resolveSessionTitle(client, directory, sessionID) {
     })
     return limit((result?.data ?? result)?.title)
   } catch (error) {
-    console.error(`[backeer] could not resolve session title: ${limit(error, 500)}`)
+    reporter.debug("Session title unavailable", error)
     return ""
   }
 }
 
-async function publishQuestion(config, request, identity, client, directory) {
+async function publishQuestion(
+  config,
+  reporter,
+  request,
+  identity,
+  client,
+  directory,
+) {
   const questions = Array.isArray(request.questions) ? request.questions : []
   if (questions.length === 0) return
 
@@ -243,6 +316,7 @@ async function publishQuestion(config, request, identity, client, directory) {
     client,
     directory,
     identity.sessionID,
+    reporter,
   )
   const payload = [
     { key: "OpenCode session", value: sessionTitle },
@@ -282,7 +356,7 @@ async function publishQuestion(config, request, identity, client, directory) {
     notify: true,
     direction: "in",
   })
-  console.log(`[backeer] question event accepted (${result.status})`)
+  reporter.success("Question sent", `HTTP ${result.status}`)
 }
 
 function stableHash(value) {
@@ -294,12 +368,20 @@ function stableHash(value) {
   return (hash >>> 0).toString(16).padStart(8, "0")
 }
 
-async function publishTodoCompletion(config, request, eventID, client, directory) {
+async function publishTodoCompletion(
+  config,
+  reporter,
+  request,
+  eventID,
+  client,
+  directory,
+) {
   const todos = request.todos
   const sessionTitle = await resolveSessionTitle(
     client,
     directory,
     request.sessionID,
+    reporter,
   )
   const correlation =
     typeof eventID === "string" && eventID.length > 0
@@ -341,7 +423,7 @@ async function publishTodoCompletion(config, request, eventID, client, directory
     notify: true,
     direction: "in",
   })
-  console.log(`[backeer] todo completion accepted (${result.status})`)
+  reporter.success("Todo completion sent", `HTTP ${result.status}`)
 }
 
 function parseSseFrame(frame) {
@@ -379,7 +461,7 @@ function nextSseFrame(buffer) {
   return { frame: buffer.slice(0, lfIndex), rest: buffer.slice(lfIndex + 2) }
 }
 
-async function consumeSse(response, state, onCommand, signal) {
+async function consumeSse(response, state, onCommand, signal, reporter) {
   if (!response.body) throw new Error("Backeer command stream has no body")
 
   const reader = response.body.getReader()
@@ -405,7 +487,7 @@ async function consumeSse(response, state, onCommand, signal) {
           await onCommand(JSON.parse(message.data))
         } catch (error) {
           if (error instanceof SyntaxError) {
-            console.error("[backeer] command stream returned invalid JSON")
+            reporter.error("Invalid command received", "SSE data is not valid JSON")
             continue
           }
           throw error
@@ -417,7 +499,11 @@ async function consumeSse(response, state, onCommand, signal) {
   }
 }
 
-async function runCommandStream(config, { signal, hasPending, onCommand }) {
+async function runCommandStream(
+  config,
+  reporter,
+  { signal, hasPending, onCommand },
+) {
   const state = { lastEventID: "" }
   let reconnectDelay = 1000
   let lastLoggedError = ""
@@ -448,14 +534,21 @@ async function runCommandStream(config, { signal, hasPending, onCommand }) {
 
       reconnectDelay = 1000
       lastLoggedError = ""
-      await consumeSse(response, state, onCommand, signal)
+      await consumeSse(response, state, onCommand, signal, reporter)
     } catch (error) {
       if (signal.aborted || isAbortError(error)) return
       const message = error instanceof HttpError
         ? `${error.message}: ${error.responseBody}`
         : limit(error, 500)
       if (message !== lastLoggedError) {
-        console.error(`[backeer] ${message}`)
+        const authenticationFailure = error instanceof HttpError &&
+          [401, 403].includes(error.status)
+        reporter.error(
+          authenticationFailure
+            ? "Authentication failed — run: npx backeer-opencode@latest configure"
+            : "Connection interrupted — retrying",
+          message,
+        )
         lastLoggedError = message
       }
       if (error instanceof HttpError && [401, 403, 404].includes(error.status)) {
@@ -505,17 +598,23 @@ function rememberBounded(map, key, value) {
  * protected file so it cannot accidentally be committed in opencode.json.
  */
 export default async function BackeerPlugin({ client, directory }, options = {}) {
+  const bootstrapReporter = createConsoleReporter(
+    options.logLevel ?? process.env.BACKEER_LOG_LEVEL,
+  )
   let config
   try {
     config = loadConfig(options)
   } catch (error) {
-    console.error(`[backeer] plugin disabled: ${limit(error, 500)}`)
+    bootstrapReporter.error("Plugin disabled — invalid configuration", error)
     return {}
   }
 
+  const reporter = createConsoleReporter(config.logLevel)
+
   if (!config.token) {
-    console.error(
-      `[backeer] plugin disabled: set BACKEER_INGEST_TOKEN or create ${config.tokenFile}`,
+    reporter.error(
+      "Plugin disabled — run: npx backeer-opencode@latest configure",
+      `Token not found at ${config.tokenFile}`,
     )
     return {}
   }
@@ -548,9 +647,8 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
     const previousAcknowledgement = completedCommands.get(command.id)
     if (previousAcknowledgement) {
-      await acknowledgeCommand(config, command.id, previousAcknowledgement).catch(
-        (error) => console.error(`[backeer] command ACK retry failed: ${limit(error, 500)}`),
-      )
+      await acknowledgeCommand(config, command.id, previousAcknowledgement)
+        .catch((error) => reporter.warning("Decision receipt retry failed", error))
       return
     }
     if (processingCommands.has(command.id)) return
@@ -590,7 +688,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
         errorCode: stale ? "permission_not_found" : "opencode_reply_failed",
       }
       if (stale) removePendingByRequestID(pending.requestID)
-      console.error(`[backeer] permission command failed: ${limit(error, 500)}`)
+      reporter.error("Decision could not be applied", error)
     } finally {
       processingCommands.delete(command.id)
     }
@@ -602,8 +700,21 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       processedAt: new Date().toISOString(),
     }
     rememberBounded(completedCommands, command.id, acknowledgement)
+
+    if (acknowledgement.status === "applied") {
+      reporter.applied(
+        `Decision applied: ${DECISION_LABELS[acknowledgement.decision]}`,
+      )
+    } else if (acknowledgement.status === "expired") {
+      reporter.warning("Decision expired before it could be applied")
+    } else if (acknowledgement.status === "stale") {
+      reporter.warning("Permission was already answered locally")
+    } else if (acknowledgement.status === "rejected") {
+      reporter.warning("Decision was rejected by validation")
+    }
+
     await acknowledgeCommand(config, command.id, acknowledgement).catch((error) => {
-      console.error(`[backeer] command ACK failed: ${limit(error, 500)}`)
+      reporter.warning("Decision receipt could not be sent", error)
     })
     stopCommandStreamIfIdle()
   }
@@ -614,7 +725,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     const controller = new AbortController()
     const current = {
       controller,
-      task: runCommandStream(config, {
+      task: runCommandStream(config, reporter, {
         signal: controller.signal,
         hasPending: () => pendingByExternalID.size > 0,
         onCommand: handleCommand,
@@ -632,7 +743,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       if (config.permissions && event.type === "permission.asked") {
         const identity = permissionIdentity(event.properties)
         if (!identity) {
-          console.error("[backeer] permission event is missing IDs")
+          reporter.error("Permission event is missing correlation IDs")
           return
         }
 
@@ -642,9 +753,13 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
         if (publishedPermissions.has(identity.externalId)) return
         rememberBounded(publishedPermissions, identity.externalId, true)
-        void publishPermission(config, event.properties, directory, identity).catch(
-          (error) => console.error(`[backeer] permission webhook failed: ${limit(error, 500)}`),
-        )
+        void publishPermission(
+          config,
+          reporter,
+          event.properties,
+          directory,
+          identity,
+        ).catch((error) => reporter.error("Permission request could not be sent", error))
         return
       }
 
@@ -657,7 +772,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       if (config.todos && event.type === "todo.updated") {
         const { sessionID, todos } = event.properties
         if (typeof sessionID !== "string" || !Array.isArray(todos)) {
-          console.error("[backeer] todo event is missing a valid session or list")
+          reporter.error("Todo event is missing a valid session or list")
           return
         }
 
@@ -669,13 +784,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
         void publishTodoCompletion(
           config,
+          reporter,
           event.properties,
           event.id,
           client,
           directory,
-        ).catch(
-          (error) => console.error(`[backeer] todo webhook failed: ${limit(error, 500)}`),
-        )
+        ).catch((error) => reporter.error("Todo completion could not be sent", error))
         return
       }
 
@@ -685,7 +799,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       ) {
         const identity = questionIdentity(event.properties)
         if (!identity) {
-          console.error("[backeer] question event is missing IDs")
+          reporter.error("Question event is missing correlation IDs")
           return
         }
         if (publishedQuestions.has(identity.externalId)) return
@@ -693,13 +807,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
         void publishQuestion(
           config,
+          reporter,
           event.properties,
           identity,
           client,
           directory,
-        ).catch(
-          (error) => console.error(`[backeer] question webhook failed: ${limit(error, 500)}`),
-        )
+        ).catch((error) => reporter.error("Question could not be sent", error))
       }
     },
     dispose: async () => {