backeer-opencode 0.1.2 → 0.1.4

package/src/management.js

@@ -0,0 +1,207 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, resolve } from "node:path"
+
+export const PLUGIN_VERSION = "0.1.4"
+
+const COMMAND_DESCRIPTION =
+  "Show Backeer status or manage its token: /backeer [status|token|token-file PATH]"
+
+function tokenFileState(path) {
+  try {
+    const stats = statSync(path)
+    const mode = (stats.mode & 0o777).toString(8).padStart(3, "0")
+    return stats.isFile() ? `present (mode ${mode})` : "not a regular file"
+  } catch {
+    return "missing"
+  }
+}
+
+function cleanPathArgument(value) {
+  const path = value.trim()
+  if (
+    path.length >= 2 &&
+    ((path.startsWith('"') && path.endsWith('"')) ||
+      (path.startsWith("'") && path.endsWith("'")))
+  ) {
+    return path.slice(1, -1)
+  }
+  return path
+}
+
+function writeTokenAtomically(path, token) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(temporaryPath, `${token}\n`, { encoding: "utf8", mode: 0o600 })
+  chmodSync(temporaryPath, 0o600)
+  renameSync(temporaryPath, path)
+}
+
+export function rotateTokenFromFile(config, sourcePathValue) {
+  if (!sourcePathValue.trim()) throw new Error("A token file path is required")
+  const sourcePath = resolve(cleanPathArgument(sourcePathValue))
+
+  const sourceStats = statSync(sourcePath)
+  if (!sourceStats.isFile()) throw new Error("The token source is not a regular file")
+  if ((sourceStats.mode & 0o077) !== 0) {
+    throw new Error("The token source must not be readable by group or other users")
+  }
+
+  const token = readFileSync(sourcePath, "utf8").trim()
+  if (!token || /\s/.test(token)) {
+    throw new Error("The token source must contain exactly one non-empty token")
+  }
+
+  const targetPath = resolve(config.tokenFile)
+  if (sourcePath !== targetPath) writeTokenAtomically(targetPath, token)
+  else chmodSync(targetPath, 0o600)
+  config.token = token
+  config.tokenSource = "file"
+  return targetPath
+}
+
+async function probeGateway(config) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 3000)
+  try {
+    const response = await fetch(config.origin, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: controller.signal,
+    })
+    return `reachable (HTTP ${response.status}; authentication not tested)`
+  } catch {
+    return "unreachable"
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+async function buildStatus(config, permissionController) {
+  const gateway = await probeGateway(config)
+  const permissionStatus = permissionController.status()
+  return [
+    "## Backeer status",
+    "",
+    `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Gateway: ${config.origin.origin} — ${gateway}`,
+    `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
+    `- Token file: ${config.tokenFile} — ${tokenFileState(config.tokenFile)}`,
+    `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
+    `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
+    `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Command stream: ${permissionStatus.stream}`,
+    `- Pending permissions: ${permissionStatus.pending}`,
+    `- Log level: ${config.logLevel}`,
+    "",
+    "The token value is never displayed.",
+  ].join("\n")
+}
+
+function helpMessage() {
+  return [
+    "## Backeer commands",
+    "",
+    "- `/backeer` or `/backeer status` — show integration status",
+    "- `/backeer token` — show secure token-change instructions",
+    "- `/backeer token-file /absolute/protected/path` — import and activate a token",
+    "",
+    "Never place a token directly in a slash command. Slash-command arguments may be stored in session history.",
+  ].join("\n")
+}
+
+function tokenInstructions() {
+  return [
+    "## Change the Backeer token securely",
+    "",
+    "Do not paste the token into OpenCode or `/backeer` arguments.",
+    "",
+    "Use either:",
+    "",
+    "1. Hidden terminal input: `npx backeer-opencode@latest configure`",
+    "2. A protected file: `chmod 600 /path/to/token && /backeer token-file /path/to/token`",
+    "",
+    "`token-file` activates the new token immediately; no OpenCode restart is required.",
+  ].join("\n")
+}
+
+async function sendCommandMessage(client, sessionID, text) {
+  if (typeof client?.session?.prompt !== "function") {
+    throw new Error("OpenCode session messaging is unavailable")
+  }
+  await client.session.prompt({
+    path: { id: sessionID },
+    body: {
+      noReply: true,
+      parts: [{ type: "text", text, ignored: true }],
+    },
+  })
+}
+
+export function registerBackeerCommand(opencodeConfig) {
+  opencodeConfig.command ??= {}
+  opencodeConfig.command.backeer = {
+    template: "",
+    description: COMMAND_DESCRIPTION,
+  }
+}
+
+export function createBackeerCommandHandler({
+  client,
+  config,
+  permissionController,
+  reporter,
+}) {
+  return async (input, output) => {
+    if (input.command !== "backeer") return
+    output.parts.length = 0
+
+    const argumentsValue = (input.arguments ?? "").trim()
+    const separator = argumentsValue.indexOf(" ")
+    const subcommand = (
+      separator === -1 ? argumentsValue : argumentsValue.slice(0, separator)
+    ).toLowerCase()
+    const subcommandArguments = separator === -1
+      ? ""
+      : argumentsValue.slice(separator + 1).trim()
+
+    let message
+    try {
+      if (!subcommand || subcommand === "status") {
+        message = await buildStatus(config, permissionController)
+      } else if (subcommand === "token") {
+        message = tokenInstructions()
+      } else if (subcommand === "token-file") {
+        const targetPath = rotateTokenFromFile(config, subcommandArguments)
+        permissionController.refreshCredentials()
+        reporter.success("Access token updated")
+        message = [
+          "## Backeer token updated",
+          "",
+          `- Protected token file: ${targetPath}`,
+          "- File mode: 600",
+          "- The new token is active immediately.",
+        ].join("\n")
+      } else {
+        message = helpMessage()
+      }
+    } catch (error) {
+      reporter.error("Access token could not be updated", error)
+      message = [
+        "## Backeer command failed",
+        "",
+        error instanceof Error ? error.message : String(error),
+        "",
+        "Use `/backeer token` for secure token-change instructions.",
+      ].join("\n")
+    }
+
+    await sendCommandMessage(client, input.sessionID, message)
+  }
+}

package/src/permission-controller.js

@@ -0,0 +1,195 @@
+import { HttpError, postJsonWithRetry } from "./http.js"
+import { runCommandStream } from "./sse.js"
+import { rememberBounded } from "./utilities.js"
+
+const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
+const DECISION_LABELS = {
+  once: "Allow once",
+  always: "Always allow",
+  reject: "Reject",
+}
+
+async function replyToOpenCode(client, pending, decision) {
+  const result = await client.postSessionIdPermissionsPermissionId({
+    path: { id: pending.sessionID, permissionID: pending.requestID },
+    query: { directory: pending.directory },
+    body: { response: decision },
+    throwOnError: true,
+  })
+
+  if (result?.data === false || result === false) {
+    throw new HttpError("OpenCode did not apply the permission reply", 409)
+  }
+}
+
+async function acknowledgeCommand(config, commandID, acknowledgement) {
+  const url = new URL(
+    `/v1/commands/${encodeURIComponent(commandID)}/ack`,
+    config.origin,
+  )
+  await postJsonWithRetry(config, url, acknowledgement)
+}
+
+export function createPermissionController({
+  config,
+  reporter,
+  client,
+  directory,
+}) {
+  const pendingByExternalID = new Map()
+  const externalIDByRequestID = new Map()
+  const processingCommands = new Set()
+  const completedCommands = new Map()
+  const publishedPermissions = new Map()
+  let commandStream
+  let disposed = false
+
+  function removePendingByRequestID(requestID) {
+    const externalId = externalIDByRequestID.get(requestID)
+    if (!externalId) return
+    externalIDByRequestID.delete(requestID)
+    pendingByExternalID.delete(externalId)
+  }
+
+  function stopCommandStreamIfIdle() {
+    if (pendingByExternalID.size === 0) commandStream?.controller.abort()
+  }
+
+  async function handleCommand(command) {
+    if (!command || typeof command !== "object") return
+    if (command.type !== "opencode_permission_reply") return
+    if (typeof command.id !== "string" || command.id.length > 200) return
+
+    const previousAcknowledgement = completedCommands.get(command.id)
+    if (previousAcknowledgement) {
+      await acknowledgeCommand(config, command.id, previousAcknowledgement)
+        .catch((error) => reporter.warning("Decision receipt retry failed", error))
+      return
+    }
+    if (processingCommands.has(command.id)) return
+    if (typeof command.externalId !== "string") return
+
+    const pending = pendingByExternalID.get(command.externalId)
+    if (!pending) return
+
+    processingCommands.add(command.id)
+    let acknowledgement
+    try {
+      if (!ALLOWED_DECISIONS.has(command.decision)) {
+        acknowledgement = { status: "rejected", errorCode: "invalid_decision" }
+      } else {
+        const expiresAt = Date.parse(command.expiresAt)
+        if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+          acknowledgement = { status: "expired", decision: command.decision }
+        } else if (command.decision === "always" && command.confirmed !== true) {
+          acknowledgement = {
+            status: "rejected",
+            decision: command.decision,
+            errorCode: "confirmation_required",
+          }
+        } else {
+          await replyToOpenCode(client, pending, command.decision)
+          acknowledgement = { status: "applied", decision: command.decision }
+          removePendingByRequestID(pending.requestID)
+        }
+      }
+    } catch (error) {
+      const stale = error instanceof HttpError && error.status === 404
+      acknowledgement = {
+        status: stale ? "stale" : "failed",
+        decision: ALLOWED_DECISIONS.has(command.decision)
+          ? command.decision
+          : undefined,
+        errorCode: stale ? "permission_not_found" : "opencode_reply_failed",
+      }
+      if (stale) removePendingByRequestID(pending.requestID)
+      reporter.error("Decision could not be applied", error)
+    } finally {
+      processingCommands.delete(command.id)
+    }
+
+    acknowledgement = {
+      ...acknowledgement,
+      type: "opencode_permission_reply_ack",
+      externalId: command.externalId,
+      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) => {
+      reporter.warning("Decision receipt could not be sent", error)
+    })
+    stopCommandStreamIfIdle()
+  }
+
+  function ensureCommandStream() {
+    if (disposed || commandStream || pendingByExternalID.size === 0) return
+
+    const controller = new AbortController()
+    const current = {
+      controller,
+      task: runCommandStream(config, reporter, {
+        signal: controller.signal,
+        hasPending: () => pendingByExternalID.size > 0,
+        onCommand: handleCommand,
+      }),
+    }
+    commandStream = current
+    void current.task.finally(() => {
+      if (commandStream === current) commandStream = undefined
+      if (!disposed && pendingByExternalID.size > 0) ensureCommandStream()
+    })
+  }
+
+  return {
+    register(identity) {
+      pendingByExternalID.set(identity.externalId, { ...identity, directory })
+      externalIDByRequestID.set(identity.requestID, identity.externalId)
+      ensureCommandStream()
+
+      if (publishedPermissions.has(identity.externalId)) return false
+      rememberBounded(publishedPermissions, identity.externalId, true)
+      return true
+    },
+
+    resolveLocally(requestID) {
+      removePendingByRequestID(requestID)
+      stopCommandStreamIfIdle()
+    },
+
+    refreshCredentials() {
+      commandStream?.controller.abort()
+      if (!commandStream) ensureCommandStream()
+    },
+
+    status() {
+      return {
+        pending: pendingByExternalID.size,
+        stream: commandStream ? "active" : "idle",
+      }
+    },
+
+    async dispose() {
+      disposed = true
+      commandStream?.controller.abort()
+      await commandStream?.task.catch(() => {})
+      pendingByExternalID.clear()
+      externalIDByRequestID.clear()
+      processingCommands.clear()
+      completedCommands.clear()
+      publishedPermissions.clear()
+    },
+  }
+}

package/src/plugin.js

@@ -0,0 +1,160 @@
+import { loadConfig } from "./config.js"
+import {
+  permissionIdentity,
+  publishPermission,
+  publishQuestion,
+  publishTodoCompletion,
+  questionIdentity,
+} from "./event-publishers.js"
+import {
+  createBackeerCommandHandler,
+  registerBackeerCommand,
+} from "./management.js"
+import { createPermissionController } from "./permission-controller.js"
+import { createConsoleReporter } from "./reporter.js"
+import { rememberBounded } from "./utilities.js"
+
+/**
+ * OpenCode server plugin entrypoint.
+ *
+ * Supported options: origin, tokenFile, permissions, questions, todos, logLevel.
+ * The ingest token is intentionally accepted only through the environment or a
+ * 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) {
+    bootstrapReporter.error("Plugin disabled — invalid configuration", error)
+    return {}
+  }
+
+  const reporter = createConsoleReporter(config.logLevel)
+
+  const permissionController = createPermissionController({
+    config,
+    reporter,
+    client,
+    directory,
+  })
+  const todoCompletionBySessionID = new Map()
+  const publishedQuestions = new Map()
+  const handleBackeerCommand = createBackeerCommandHandler({
+    client,
+    config,
+    permissionController,
+    reporter,
+  })
+
+  if (!config.token) {
+    reporter.error(
+      "Notifications disabled — use /backeer token",
+      `Token not found at ${config.tokenFile}`,
+    )
+  }
+
+  async function handlePermissionAsked(event) {
+    const identity = permissionIdentity(event.properties)
+    if (!identity) {
+      reporter.error("Permission event is missing correlation IDs")
+      return
+    }
+    if (!permissionController.register(identity)) return
+
+    void publishPermission(
+      config,
+      reporter,
+      event.properties,
+      directory,
+      identity,
+    ).catch((error) => reporter.error("Permission request could not be sent", error))
+  }
+
+  async function handleTodoUpdated(event) {
+    const { sessionID, todos } = event.properties
+    if (typeof sessionID !== "string" || !Array.isArray(todos)) {
+      reporter.error("Todo event is missing a valid session or list")
+      return
+    }
+
+    const isComplete = todos.length > 0 &&
+      todos.every((todo) => todo?.status === "completed")
+    const wasComplete = todoCompletionBySessionID.get(sessionID) === true
+    rememberBounded(todoCompletionBySessionID, sessionID, isComplete)
+    if (!isComplete || wasComplete) return
+
+    void publishTodoCompletion(
+      config,
+      reporter,
+      event.properties,
+      event.id,
+      client,
+      directory,
+    ).catch((error) => reporter.error("Todo completion could not be sent", error))
+  }
+
+  async function handleQuestionAsked(event) {
+    const identity = questionIdentity(event.properties)
+    if (!identity) {
+      reporter.error("Question event is missing correlation IDs")
+      return
+    }
+    if (publishedQuestions.has(identity.externalId)) return
+    rememberBounded(publishedQuestions, identity.externalId, true)
+
+    void publishQuestion(
+      config,
+      reporter,
+      event.properties,
+      identity,
+      client,
+      directory,
+    ).catch((error) => reporter.error("Question could not be sent", error))
+  }
+
+  return {
+    config: async (opencodeConfig) => {
+      registerBackeerCommand(opencodeConfig)
+    },
+
+    "command.execute.before": handleBackeerCommand,
+
+    event: async ({ event }) => {
+      if (!config.token) return
+
+      if (config.permissions && event.type === "permission.asked") {
+        await handlePermissionAsked(event)
+        return
+      }
+
+      if (config.permissions && event.type === "permission.replied") {
+        permissionController.resolveLocally(
+          event.properties.requestID ?? event.properties.id,
+        )
+        return
+      }
+
+      if (config.todos && event.type === "todo.updated") {
+        await handleTodoUpdated(event)
+        return
+      }
+
+      if (
+        config.questions &&
+        (event.type === "question.asked" || event.type === "question.v2.asked")
+      ) {
+        await handleQuestionAsked(event)
+      }
+    },
+
+    dispose: async () => {
+      await permissionController.dispose()
+      todoCompletionBySessionID.clear()
+      publishedQuestions.clear()
+    },
+  }
+}

package/src/reporter.js

@@ -0,0 +1,60 @@
+import { limit } from "./utilities.js"
+
+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
+
+export function normalizeLogLevel(value) {
+  const level = String(value ?? "info").trim().toLowerCase()
+  return LOG_LEVELS.has(level) ? level : "info"
+}
+
+export 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),
+  }
+}