backeer-opencode 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.1.5 - 2026-09-01
+
+- Check the NPM registry for a newer Backeer plugin version once per day.
+- Notify the OpenCode agent once per session when an update is available.
+- Add `/backeer update-check` for an explicit registry check.
+- Add `/backeer update` to delegate an exact-version installation and
+  verification workflow to the OpenCode agent.
+- Require the agent workflow to preserve the token and avoid `@latest` cache
+  ambiguity.
+
 ## 0.1.4 - 2026-09-01
 
 - Add `/backeer` and `/backeer status` for an in-session integration report.

package/README.md

@@ -156,6 +156,8 @@ The plugin registers a `/backeer` command inside OpenCode:
 ```text
 /backeer
 /backeer status
+/backeer update-check
+/backeer update
 /backeer token
 /backeer token-file /absolute/path/to/a/protected-token-file
 ```
@@ -173,6 +175,19 @@ atomically copies it to the configured token location, applies mode `0600`, and
 activates it immediately without restarting OpenCode. The source file is not
 removed.
 
+The plugin checks the NPM registry at most once every 24 hours. When a newer
+version exists, it adds one synthetic update notice to each OpenCode session so
+the agent can inform the user. The notice never authorizes installation by
+itself.
+
+`/backeer update-check` performs an explicit check. `/backeer update` is the
+user authorization point: it gives the OpenCode agent an exact-version install
+command, requires verification of both the global version pin and package
+cache, and forbids reading or changing the Backeer token. The agent does not
+terminate the active OpenCode process; restart OpenCode after a successful
+update. Exact versions are used instead of `@latest` to avoid stale OpenCode
+package caches.
+
 ## Events and decisions
 
 The plugin publishes:

package/dist/backeer-permission.js

@@ -357,8 +357,130 @@ import {
   writeFileSync
 } from "node:fs";
 import { dirname, resolve } from "node:path";
-var PLUGIN_VERSION = "0.1.4";
-var COMMAND_DESCRIPTION = "Show Backeer status or manage its token: /backeer [status|token|token-file PATH]";
+
+// src/updates.js
+var PLUGIN_VERSION = "0.1.5";
+var PACKAGE_NAME = "backeer-opencode";
+var NPM_REGISTRY_URL = "https://registry.npmjs.org";
+var CHECK_TIMEOUT_MS = 3e3;
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function parseVersion(value) {
+  const match = String(value).trim().match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/
+  );
+  if (!match) return;
+  return {
+    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4]
+  };
+}
+function isVersionNewer(latestValue, currentValue) {
+  const latest = parseVersion(latestValue);
+  const current = parseVersion(currentValue);
+  if (!latest || !current) return false;
+  for (let index = 0; index < 3; index++) {
+    if (latest.parts[index] > current.parts[index]) return true;
+    if (latest.parts[index] < current.parts[index]) return false;
+  }
+  if (!latest.prerelease && current.prerelease) return true;
+  if (latest.prerelease && !current.prerelease) return false;
+  return Boolean(
+    latest.prerelease && current.prerelease && latest.prerelease !== current.prerelease
+  );
+}
+function createUpdateChecker({
+  fetchImplementation = globalThis.fetch,
+  now = () => Date.now()
+} = {}) {
+  let checkedAt = 0;
+  let cachedResult;
+  let pendingCheck;
+  async function fetchLatest() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+    try {
+      const response = await fetchImplementation(
+        `${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`,
+        { signal: controller.signal }
+      );
+      if (!response.ok) return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+      const data = await response.json();
+      const latestVersion = typeof data?.version === "string" ? data.version.trim() : "";
+      if (!parseVersion(latestVersion)) {
+        return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+      }
+      if (!isVersionNewer(latestVersion, PLUGIN_VERSION)) {
+        return {
+          state: "current",
+          currentVersion: PLUGIN_VERSION,
+          latestVersion
+        };
+      }
+      return {
+        state: "available",
+        currentVersion: PLUGIN_VERSION,
+        latestVersion,
+        updateCommand: `opencode plugin ${PACKAGE_NAME}@${latestVersion} -g --force`
+      };
+    } catch {
+      return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  return {
+    async check({ force = false } = {}) {
+      if (!force && checkedAt && now() - checkedAt < CHECK_INTERVAL_MS) {
+        return cachedResult;
+      }
+      if (pendingCheck) return pendingCheck;
+      pendingCheck = fetchLatest().then((result) => {
+        cachedResult = result;
+        checkedAt = now();
+        return result;
+      }).finally(() => {
+        pendingCheck = void 0;
+      });
+      return pendingCheck;
+    }
+  };
+}
+function formatAgentUpdateInstruction(info) {
+  return [
+    "[BACKEER UPDATE REQUESTED]",
+    `The user explicitly requested the Backeer OpenCode plugin update from v${info.currentVersion} to v${info.latestVersion}.`,
+    `Run exactly: ${info.updateCommand}`,
+    "Then verify that the global OpenCode config is pinned to the exact new version and that the matching package exists in the OpenCode cache.",
+    "Do not read, print, replace, or otherwise expose the Backeer token.",
+    "Do not use @latest and do not claim success until both installation and verification pass.",
+    "Do not terminate the active OpenCode process; tell the user to restart OpenCode after success."
+  ].join("\n");
+}
+function createUpdateNoticeHook(updateChecker) {
+  const notifiedSessions = /* @__PURE__ */ new Set();
+  return async (input, output) => {
+    if (notifiedSessions.has(input.sessionID)) return;
+    notifiedSessions.add(input.sessionID);
+    const info = await updateChecker.check();
+    if (info.state !== "available") return;
+    output.parts.push({
+      id: `prt_backeer-update-${Date.now()}`,
+      sessionID: input.sessionID,
+      messageID: output.message.id,
+      type: "text",
+      synthetic: true,
+      text: [
+        "[BACKEER UPDATE AVAILABLE]",
+        `Backeer OpenCode plugin v${info.latestVersion} is available; current version is v${info.currentVersion}.`,
+        "Inform the user that an update is available and suggest `/backeer update`.",
+        "Do not install it solely because of this notice."
+      ].join("\n")
+    });
+  };
+}
+
+// src/management.js
+var COMMAND_DESCRIPTION = "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]";
 function tokenFileState(path) {
   try {
     const stats = statSync(path);
@@ -418,13 +540,24 @@ async function probeGateway(config) {
     clearTimeout(timeout);
   }
 }
-async function buildStatus(config, permissionController) {
-  const gateway = await probeGateway(config);
+function updateStatus(info) {
+  if (info.state === "available") {
+    return `v${info.latestVersion} available \u2014 use /backeer update`;
+  }
+  if (info.state === "current") return `current (v${info.currentVersion})`;
+  return "check unavailable";
+}
+async function buildStatus(config, permissionController, updateChecker) {
+  const [gateway, update] = await Promise.all([
+    probeGateway(config),
+    updateChecker.check()
+  ]);
   const permissionStatus = permissionController.status();
   return [
     "## Backeer status",
     "",
     `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Update: ${updateStatus(update)}`,
     `- Gateway: ${config.origin.origin} \u2014 ${gateway}`,
     `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
     `- Token file: ${config.tokenFile} \u2014 ${tokenFileState(config.tokenFile)}`,
@@ -443,6 +576,8 @@ function helpMessage() {
     "## Backeer commands",
     "",
     "- `/backeer` or `/backeer status` \u2014 show integration status",
+    "- `/backeer update-check` \u2014 check NPM for a newer version",
+    "- `/backeer update` \u2014 ask the OpenCode agent to install and verify it",
     "- `/backeer token` \u2014 show secure token-change instructions",
     "- `/backeer token-file /absolute/protected/path` \u2014 import and activate a token",
     "",
@@ -486,7 +621,8 @@ function createBackeerCommandHandler({
   client,
   config,
   permissionController,
-  reporter
+  reporter,
+  updateChecker
 }) {
   return async (input, output) => {
     if (input.command !== "backeer") return;
@@ -498,7 +634,26 @@ function createBackeerCommandHandler({
     let message;
     try {
       if (!subcommand || subcommand === "status") {
-        message = await buildStatus(config, permissionController);
+        message = await buildStatus(config, permissionController, updateChecker);
+      } else if (subcommand === "update-check") {
+        const update = await updateChecker.check({ force: true });
+        message = [
+          "## Backeer update check",
+          "",
+          update.state === "available" ? `Version ${update.latestVersion} is available; current version is ${update.currentVersion}. Use \`/backeer update\` to let the OpenCode agent install and verify it.` : update.state === "current" ? `Backeer is current at version ${update.currentVersion}.` : "The NPM registry could not be reached. No update was attempted."
+        ].join("\n");
+      } else if (subcommand === "update") {
+        const update = await updateChecker.check({ force: true });
+        if (update.state === "available") {
+          output.parts.push({
+            type: "text",
+            text: formatAgentUpdateInstruction(update)
+          });
+          return;
+        }
+        message = update.state === "current" ? `## Backeer update
+
+Backeer is already current at version ${update.currentVersion}.` : "## Backeer update\n\nThe NPM registry could not be reached. No update was attempted.";
       } else if (subcommand === "token") {
         message = tokenInstructions();
       } else if (subcommand === "token-file") {
@@ -835,12 +990,15 @@ async function BackeerPlugin({ client, directory }, options = {}) {
   });
   const todoCompletionBySessionID = /* @__PURE__ */ new Map();
   const publishedQuestions = /* @__PURE__ */ new Map();
+  const updateChecker = createUpdateChecker();
   const handleBackeerCommand = createBackeerCommandHandler({
     client,
     config,
     permissionController,
-    reporter
+    reporter,
+    updateChecker
   });
+  const handleUpdateNotice = createUpdateNoticeHook(updateChecker);
   if (!config.token) {
     reporter.error(
       "Notifications disabled \u2014 use /backeer token",
@@ -903,6 +1061,7 @@ async function BackeerPlugin({ client, directory }, options = {}) {
       registerBackeerCommand(opencodeConfig);
     },
     "command.execute.before": handleBackeerCommand,
+    "chat.message": handleUpdateNotice,
     event: async ({ event }) => {
       if (!config.token) return;
       if (config.permissions && event.type === "permission.asked") {

package/package.json

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

package/src/management.js

@@ -8,10 +8,13 @@ import {
 } from "node:fs"
 import { dirname, resolve } from "node:path"
 
-export const PLUGIN_VERSION = "0.1.4"
+import {
+  formatAgentUpdateInstruction,
+  PLUGIN_VERSION,
+} from "./updates.js"
 
 const COMMAND_DESCRIPTION =
-  "Show Backeer status or manage its token: /backeer [status|token|token-file PATH]"
+  "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]"
 
 function tokenFileState(path) {
   try {
@@ -83,13 +86,25 @@ async function probeGateway(config) {
   }
 }
 
-async function buildStatus(config, permissionController) {
-  const gateway = await probeGateway(config)
+function updateStatus(info) {
+  if (info.state === "available") {
+    return `v${info.latestVersion} available — use /backeer update`
+  }
+  if (info.state === "current") return `current (v${info.currentVersion})`
+  return "check unavailable"
+}
+
+async function buildStatus(config, permissionController, updateChecker) {
+  const [gateway, update] = await Promise.all([
+    probeGateway(config),
+    updateChecker.check(),
+  ])
   const permissionStatus = permissionController.status()
   return [
     "## Backeer status",
     "",
     `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Update: ${updateStatus(update)}`,
     `- Gateway: ${config.origin.origin} — ${gateway}`,
     `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
     `- Token file: ${config.tokenFile} — ${tokenFileState(config.tokenFile)}`,
@@ -109,6 +124,8 @@ function helpMessage() {
     "## Backeer commands",
     "",
     "- `/backeer` or `/backeer status` — show integration status",
+    "- `/backeer update-check` — check NPM for a newer version",
+    "- `/backeer update` — ask the OpenCode agent to install and verify it",
     "- `/backeer token` — show secure token-change instructions",
     "- `/backeer token-file /absolute/protected/path` — import and activate a token",
     "",
@@ -157,6 +174,7 @@ export function createBackeerCommandHandler({
   config,
   permissionController,
   reporter,
+  updateChecker,
 }) {
   return async (input, output) => {
     if (input.command !== "backeer") return
@@ -174,7 +192,30 @@ export function createBackeerCommandHandler({
     let message
     try {
       if (!subcommand || subcommand === "status") {
-        message = await buildStatus(config, permissionController)
+        message = await buildStatus(config, permissionController, updateChecker)
+      } else if (subcommand === "update-check") {
+        const update = await updateChecker.check({ force: true })
+        message = [
+          "## Backeer update check",
+          "",
+          update.state === "available"
+            ? `Version ${update.latestVersion} is available; current version is ${update.currentVersion}. Use \`/backeer update\` to let the OpenCode agent install and verify it.`
+            : update.state === "current"
+              ? `Backeer is current at version ${update.currentVersion}.`
+              : "The NPM registry could not be reached. No update was attempted.",
+        ].join("\n")
+      } else if (subcommand === "update") {
+        const update = await updateChecker.check({ force: true })
+        if (update.state === "available") {
+          output.parts.push({
+            type: "text",
+            text: formatAgentUpdateInstruction(update),
+          })
+          return
+        }
+        message = update.state === "current"
+          ? `## Backeer update\n\nBackeer is already current at version ${update.currentVersion}.`
+          : "## Backeer update\n\nThe NPM registry could not be reached. No update was attempted."
       } else if (subcommand === "token") {
         message = tokenInstructions()
       } else if (subcommand === "token-file") {

package/src/plugin.js

@@ -12,6 +12,10 @@ import {
 } from "./management.js"
 import { createPermissionController } from "./permission-controller.js"
 import { createConsoleReporter } from "./reporter.js"
+import {
+  createUpdateChecker,
+  createUpdateNoticeHook,
+} from "./updates.js"
 import { rememberBounded } from "./utilities.js"
 
 /**
@@ -43,12 +47,15 @@ export default async function BackeerPlugin({ client, directory }, options = {})
   })
   const todoCompletionBySessionID = new Map()
   const publishedQuestions = new Map()
+  const updateChecker = createUpdateChecker()
   const handleBackeerCommand = createBackeerCommandHandler({
     client,
     config,
     permissionController,
     reporter,
+    updateChecker,
   })
+  const handleUpdateNotice = createUpdateNoticeHook(updateChecker)
 
   if (!config.token) {
     reporter.error(
@@ -123,6 +130,8 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
     "command.execute.before": handleBackeerCommand,
 
+    "chat.message": handleUpdateNotice,
+
     event: async ({ event }) => {
       if (!config.token) return
 

package/src/updates.js

@@ -0,0 +1,136 @@
+export const PLUGIN_VERSION = "0.1.5"
+
+const PACKAGE_NAME = "backeer-opencode"
+const NPM_REGISTRY_URL = "https://registry.npmjs.org"
+const CHECK_TIMEOUT_MS = 3000
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+export function parseVersion(value) {
+  const match = String(value).trim().match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/,
+  )
+  if (!match) return
+  return {
+    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4],
+  }
+}
+
+export function isVersionNewer(latestValue, currentValue) {
+  const latest = parseVersion(latestValue)
+  const current = parseVersion(currentValue)
+  if (!latest || !current) return false
+
+  for (let index = 0; index < 3; index++) {
+    if (latest.parts[index] > current.parts[index]) return true
+    if (latest.parts[index] < current.parts[index]) return false
+  }
+  if (!latest.prerelease && current.prerelease) return true
+  if (latest.prerelease && !current.prerelease) return false
+  return Boolean(
+    latest.prerelease &&
+    current.prerelease &&
+    latest.prerelease !== current.prerelease,
+  )
+}
+
+export function createUpdateChecker({
+  fetchImplementation = globalThis.fetch,
+  now = () => Date.now(),
+} = {}) {
+  let checkedAt = 0
+  let cachedResult
+  let pendingCheck
+
+  async function fetchLatest() {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS)
+    try {
+      const response = await fetchImplementation(
+        `${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`,
+        { signal: controller.signal },
+      )
+      if (!response.ok) return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+      const data = await response.json()
+      const latestVersion = typeof data?.version === "string"
+        ? data.version.trim()
+        : ""
+      if (!parseVersion(latestVersion)) {
+        return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+      }
+      if (!isVersionNewer(latestVersion, PLUGIN_VERSION)) {
+        return {
+          state: "current",
+          currentVersion: PLUGIN_VERSION,
+          latestVersion,
+        }
+      }
+      return {
+        state: "available",
+        currentVersion: PLUGIN_VERSION,
+        latestVersion,
+        updateCommand:
+          `opencode plugin ${PACKAGE_NAME}@${latestVersion} -g --force`,
+      }
+    } catch {
+      return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  return {
+    async check({ force = false } = {}) {
+      if (!force && checkedAt && now() - checkedAt < CHECK_INTERVAL_MS) {
+        return cachedResult
+      }
+      if (pendingCheck) return pendingCheck
+
+      pendingCheck = fetchLatest()
+        .then((result) => {
+          cachedResult = result
+          checkedAt = now()
+          return result
+        })
+        .finally(() => { pendingCheck = undefined })
+      return pendingCheck
+    },
+  }
+}
+
+export function formatAgentUpdateInstruction(info) {
+  return [
+    "[BACKEER UPDATE REQUESTED]",
+    `The user explicitly requested the Backeer OpenCode plugin update from v${info.currentVersion} to v${info.latestVersion}.`,
+    `Run exactly: ${info.updateCommand}`,
+    "Then verify that the global OpenCode config is pinned to the exact new version and that the matching package exists in the OpenCode cache.",
+    "Do not read, print, replace, or otherwise expose the Backeer token.",
+    "Do not use @latest and do not claim success until both installation and verification pass.",
+    "Do not terminate the active OpenCode process; tell the user to restart OpenCode after success.",
+  ].join("\n")
+}
+
+export function createUpdateNoticeHook(updateChecker) {
+  const notifiedSessions = new Set()
+
+  return async (input, output) => {
+    if (notifiedSessions.has(input.sessionID)) return
+    notifiedSessions.add(input.sessionID)
+
+    const info = await updateChecker.check()
+    if (info.state !== "available") return
+    output.parts.push({
+      id: `prt_backeer-update-${Date.now()}`,
+      sessionID: input.sessionID,
+      messageID: output.message.id,
+      type: "text",
+      synthetic: true,
+      text: [
+        "[BACKEER UPDATE AVAILABLE]",
+        `Backeer OpenCode plugin v${info.latestVersion} is available; current version is v${info.currentVersion}.`,
+        "Inform the user that an update is available and suggest `/backeer update`.",
+        "Do not install it solely because of this notice.",
+      ].join("\n"),
+    })
+  }
+}