backeer-opencode 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.2.1 - 2026-09-01
+
+- Add `/backeer doctor` for read-only local configuration, protected token,
+  source authentication, gateway capability, and APNs diagnostics.
+- Add `/backeer test` to send a uniquely correlated end-to-end mobile test
+  notification.
+- Keep doctor reports and command output free of bearer token values.
+
 ## 0.2.0 - 2026-09-01
 
 - Notify when an OpenCode assistant run completes successfully.

package/README.md

@@ -177,6 +177,8 @@ The plugin registers a `/backeer` command inside OpenCode:
 ```text
 /backeer
 /backeer status
+/backeer doctor
+/backeer test
 /backeer update-check
 /backeer update
 /backeer token
@@ -188,6 +190,16 @@ notification switches and lifecycle thresholds, command-stream state, pending
 permissions, and log level. It never displays the token. Gateway reachability
 does not validate the source credential.
 
+`/backeer doctor` performs a read-only diagnostic pass. It verifies the local
+configuration, protected token-file permissions, source authentication, event
+and command capabilities, and gateway APNs readiness. It does not create an
+event, open a command stream, or display the bearer token.
+
+`/backeer test` publishes one uniquely correlated, non-actionable application
+event and asks the gateway to deliver a real push notification. Use it after
+installation, token rotation, or network changes to verify the complete path
+from OpenCode to the phone.
+
 `/backeer token` displays safe rotation instructions. Never paste a raw token
 into slash-command arguments because OpenCode may retain command text in session
 history. To rotate from inside OpenCode, first place the new token in an absolute

package/dist/backeer-permission.js

@@ -140,6 +140,7 @@ function loadConfig(options = {}) {
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
+    sourceHealthEndpoint: new URL("/v1/source/health", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
     token: loadedToken.token,
     tokenSource: loadedToken.source,
@@ -391,13 +392,17 @@ import {
   mkdirSync,
   readFileSync as readFileSync2,
   renameSync,
-  statSync,
+  statSync as statSync2,
   writeFileSync
 } from "node:fs";
 import { dirname, resolve } from "node:path";
 
+// src/diagnostics.js
+import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+
 // src/updates.js
-var PLUGIN_VERSION = "0.2.0";
+var PLUGIN_VERSION = "0.2.1";
 var PACKAGE_NAME = "backeer-opencode";
 var NPM_REGISTRY_URL = "https://registry.npmjs.org";
 var CHECK_TIMEOUT_MS = 3e3;
@@ -517,11 +522,129 @@ function createUpdateNoticeHook(updateChecker) {
   };
 }
 
+// src/diagnostics.js
+var PASS = "\u2713";
+var FAIL = "\xD7";
+var INFO = "\u2022";
+function tokenFileCheck(config) {
+  if (config.tokenSource === "environment") {
+    return { ok: true, text: "Token loaded from the environment; token file not required" };
+  }
+  try {
+    const stats = statSync(config.tokenFile);
+    const mode = stats.mode & 511;
+    if (!stats.isFile()) return { ok: false, text: "Token path is not a regular file" };
+    if ((mode & 63) !== 0) {
+      return {
+        ok: false,
+        text: `Token file mode ${mode.toString(8).padStart(3, "0")} is too permissive; expected 600`
+      };
+    }
+    return {
+      ok: true,
+      text: `Token file is protected (mode ${mode.toString(8).padStart(3, "0")})`
+    };
+  } catch {
+    return { ok: false, text: "Token file is missing or unreadable" };
+  }
+}
+async function probeSource(config, fetchImplementation = globalThis.fetch) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5e3);
+  try {
+    const response = await fetchImplementation(config.sourceHealthEndpoint, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${config.token}` },
+      signal: controller.signal
+    });
+    const responseBody = limit(await response.text(), 2e3);
+    if (!response.ok) {
+      throw new HttpError(
+        `Gateway source check failed with status ${response.status}`,
+        response.status,
+        responseBody
+      );
+    }
+    try {
+      return JSON.parse(responseBody);
+    } catch {
+      throw new Error("Gateway source check returned malformed JSON");
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function buildDoctorReport(config, { fetchImplementation = globalThis.fetch } = {}) {
+  const checks = [];
+  checks.push({ ok: true, text: `Plugin version ${PLUGIN_VERSION}` });
+  checks.push({
+    ok: config.origin.protocol === "https:",
+    text: `Gateway uses ${config.origin.protocol === "https:" ? "HTTPS" : "an insecure protocol"}: ${config.origin.origin}`
+  });
+  checks.push({
+    ok: Boolean(config.token),
+    text: config.token ? `Source token loaded from ${config.tokenSource}` : "Source token is missing"
+  });
+  checks.push(tokenFileCheck(config));
+  let source;
+  if (config.token) {
+    try {
+      const result = await probeSource(config, fetchImplementation);
+      source = result?.source;
+      checks.push({
+        ok: result?.ok === true && typeof source?.id === "string",
+        text: source?.id ? `Source authentication accepted: ${source.name || source.id} (${source.id})` : "Gateway did not return a source identity"
+      });
+      checks.push({
+        ok: result?.capabilities?.events === true && result?.capabilities?.commands === true,
+        text: result?.capabilities?.events === true && result?.capabilities?.commands === true ? "Event ingest and command stream are available" : "Event ingest or command stream is unavailable"
+      });
+      checks.push({
+        ok: result?.capabilities?.apns === true,
+        text: result?.capabilities?.apns === true ? "Gateway APNs delivery is enabled" : "Gateway APNs delivery is disabled"
+      });
+    } catch (error) {
+      const detail = error instanceof HttpError && error.status === 401 ? "Source authentication rejected (HTTP 401)" : error?.name === "AbortError" ? "Gateway source check timed out" : `Gateway source check failed: ${limit(error?.message || error, 300)}`;
+      checks.push({ ok: false, text: detail });
+    }
+  }
+  const healthy = checks.every((check) => check.ok);
+  return [
+    "## Backeer doctor",
+    "",
+    ...checks.map((check) => `${check.ok ? PASS : FAIL} ${check.text}`),
+    "",
+    healthy ? `${PASS} Result: healthy. Use \`/backeer test\` to verify phone delivery.` : `${FAIL} Result: issues found. Resolve failed checks and run \`/backeer doctor\` again.`,
+    "",
+    `${INFO} No event was created and the token value was not displayed.`
+  ].join("\n");
+}
+async function publishTestNotification(config, reporter) {
+  if (!config.token) throw new Error("Backeer source token is missing");
+  const testID = randomUUID();
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "info",
+    title: "Backeer test notification",
+    body: "OpenCode integration is connected and push delivery is working.",
+    payload: [
+      { key: "Plugin version", value: PLUGIN_VERSION },
+      { key: "Test ID", value: testID }
+    ],
+    externalId: `opencode:test:${testID}`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    notify: true,
+    direction: "in"
+  });
+  reporter.success("Test notification sent", `HTTP ${result.status}`);
+  return testID;
+}
+
 // src/management.js
-var COMMAND_DESCRIPTION = "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]";
+var COMMAND_DESCRIPTION = "Check, test, update, or manage Backeer: /backeer [status|doctor|test|update-check|update|token|token-file PATH]";
 function tokenFileState(path) {
   try {
-    const stats = statSync(path);
+    const stats = statSync2(path);
     const mode = (stats.mode & 511).toString(8).padStart(3, "0");
     return stats.isFile() ? `present (mode ${mode})` : "not a regular file";
   } catch {
@@ -546,7 +669,7 @@ function writeTokenAtomically(path, token) {
 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);
+  const sourceStats = statSync2(sourcePath);
   if (!sourceStats.isFile()) throw new Error("The token source is not a regular file");
   if ((sourceStats.mode & 63) !== 0) {
     throw new Error("The token source must not be readable by group or other users");
@@ -619,6 +742,8 @@ function helpMessage() {
     "## Backeer commands",
     "",
     "- `/backeer` or `/backeer status` \u2014 show integration status",
+    "- `/backeer doctor` \u2014 diagnose config, credentials, gateway, and APNs without creating an event",
+    "- `/backeer test` \u2014 send a real test notification to the Backeer application",
     "- `/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",
@@ -678,6 +803,17 @@ function createBackeerCommandHandler({
     try {
       if (!subcommand || subcommand === "status") {
         message = await buildStatus(config, permissionController, updateChecker);
+      } else if (subcommand === "doctor") {
+        message = await buildDoctorReport(config);
+      } else if (subcommand === "test") {
+        const testID = await publishTestNotification(config, reporter);
+        message = [
+          "## Backeer test notification",
+          "",
+          "\u2713 The gateway accepted the test event.",
+          `- Test ID: ${testID}`,
+          "- Check the Backeer application for the notification."
+        ].join("\n");
       } else if (subcommand === "update-check") {
         const update = await updateChecker.check({ force: true });
         message = [
@@ -714,7 +850,7 @@ Backeer is already current at version ${update.currentVersion}.` : "## Backeer u
         message = helpMessage();
       }
     } catch (error) {
-      reporter.error("Access token could not be updated", error);
+      reporter.error("Backeer command failed", error);
       message = [
         "## Backeer command failed",
         "",

package/package.json

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

package/src/config.js

@@ -85,6 +85,7 @@ export function loadConfig(options = {}) {
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
+    sourceHealthEndpoint: new URL("/v1/source/health", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
     token: loadedToken.token,
     tokenSource: loadedToken.source,

package/src/diagnostics.js

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto"
+import { statSync } from "node:fs"
+
+import { HttpError, postJsonWithRetry } from "./http.js"
+import { PLUGIN_VERSION } from "./updates.js"
+import { limit } from "./utilities.js"
+
+const PASS = "✓"
+const FAIL = "×"
+const INFO = "•"
+
+function tokenFileCheck(config) {
+  if (config.tokenSource === "environment") {
+    return { ok: true, text: "Token loaded from the environment; token file not required" }
+  }
+  try {
+    const stats = statSync(config.tokenFile)
+    const mode = stats.mode & 0o777
+    if (!stats.isFile()) return { ok: false, text: "Token path is not a regular file" }
+    if ((mode & 0o077) !== 0) {
+      return {
+        ok: false,
+        text: `Token file mode ${(mode).toString(8).padStart(3, "0")} is too permissive; expected 600`,
+      }
+    }
+    return {
+      ok: true,
+      text: `Token file is protected (mode ${mode.toString(8).padStart(3, "0")})`,
+    }
+  } catch {
+    return { ok: false, text: "Token file is missing or unreadable" }
+  }
+}
+
+async function probeSource(config, fetchImplementation = globalThis.fetch) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 5000)
+  try {
+    const response = await fetchImplementation(config.sourceHealthEndpoint, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${config.token}` },
+      signal: controller.signal,
+    })
+    const responseBody = limit(await response.text(), 2000)
+    if (!response.ok) {
+      throw new HttpError(
+        `Gateway source check failed with status ${response.status}`,
+        response.status,
+        responseBody,
+      )
+    }
+    try {
+      return JSON.parse(responseBody)
+    } catch {
+      throw new Error("Gateway source check returned malformed JSON")
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function buildDoctorReport(
+  config,
+  { fetchImplementation = globalThis.fetch } = {},
+) {
+  const checks = []
+  checks.push({ ok: true, text: `Plugin version ${PLUGIN_VERSION}` })
+  checks.push({
+    ok: config.origin.protocol === "https:",
+    text: `Gateway uses ${config.origin.protocol === "https:" ? "HTTPS" : "an insecure protocol"}: ${config.origin.origin}`,
+  })
+  checks.push({
+    ok: Boolean(config.token),
+    text: config.token
+      ? `Source token loaded from ${config.tokenSource}`
+      : "Source token is missing",
+  })
+  checks.push(tokenFileCheck(config))
+
+  let source
+  if (config.token) {
+    try {
+      const result = await probeSource(config, fetchImplementation)
+      source = result?.source
+      checks.push({
+        ok: result?.ok === true && typeof source?.id === "string",
+        text: source?.id
+          ? `Source authentication accepted: ${source.name || source.id} (${source.id})`
+          : "Gateway did not return a source identity",
+      })
+      checks.push({
+        ok: result?.capabilities?.events === true &&
+          result?.capabilities?.commands === true,
+        text: result?.capabilities?.events === true &&
+          result?.capabilities?.commands === true
+          ? "Event ingest and command stream are available"
+          : "Event ingest or command stream is unavailable",
+      })
+      checks.push({
+        ok: result?.capabilities?.apns === true,
+        text: result?.capabilities?.apns === true
+          ? "Gateway APNs delivery is enabled"
+          : "Gateway APNs delivery is disabled",
+      })
+    } catch (error) {
+      const detail = error instanceof HttpError && error.status === 401
+        ? "Source authentication rejected (HTTP 401)"
+        : error?.name === "AbortError"
+          ? "Gateway source check timed out"
+          : `Gateway source check failed: ${limit(error?.message || error, 300)}`
+      checks.push({ ok: false, text: detail })
+    }
+  }
+
+  const healthy = checks.every((check) => check.ok)
+  return [
+    "## Backeer doctor",
+    "",
+    ...checks.map((check) => `${check.ok ? PASS : FAIL} ${check.text}`),
+    "",
+    healthy
+      ? `${PASS} Result: healthy. Use \`/backeer test\` to verify phone delivery.`
+      : `${FAIL} Result: issues found. Resolve failed checks and run \`/backeer doctor\` again.`,
+    "",
+    `${INFO} No event was created and the token value was not displayed.`,
+  ].join("\n")
+}
+
+export async function publishTestNotification(config, reporter) {
+  if (!config.token) throw new Error("Backeer source token is missing")
+  const testID = randomUUID()
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "info",
+    title: "Backeer test notification",
+    body: "OpenCode integration is connected and push delivery is working.",
+    payload: [
+      { key: "Plugin version", value: PLUGIN_VERSION },
+      { key: "Test ID", value: testID },
+    ],
+    externalId: `opencode:test:${testID}`,
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+  })
+  reporter.success("Test notification sent", `HTTP ${result.status}`)
+  return testID
+}

package/src/management.js

@@ -8,13 +8,14 @@ import {
 } from "node:fs"
 import { dirname, resolve } from "node:path"
 
+import { buildDoctorReport, publishTestNotification } from "./diagnostics.js"
 import {
   formatAgentUpdateInstruction,
   PLUGIN_VERSION,
 } from "./updates.js"
 
 const COMMAND_DESCRIPTION =
-  "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]"
+  "Check, test, update, or manage Backeer: /backeer [status|doctor|test|update-check|update|token|token-file PATH]"
 
 function tokenFileState(path) {
   try {
@@ -129,6 +130,8 @@ function helpMessage() {
     "## Backeer commands",
     "",
     "- `/backeer` or `/backeer status` — show integration status",
+    "- `/backeer doctor` — diagnose config, credentials, gateway, and APNs without creating an event",
+    "- `/backeer test` — send a real test notification to the Backeer application",
     "- `/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",
@@ -198,6 +201,17 @@ export function createBackeerCommandHandler({
     try {
       if (!subcommand || subcommand === "status") {
         message = await buildStatus(config, permissionController, updateChecker)
+      } else if (subcommand === "doctor") {
+        message = await buildDoctorReport(config)
+      } else if (subcommand === "test") {
+        const testID = await publishTestNotification(config, reporter)
+        message = [
+          "## Backeer test notification",
+          "",
+          "✓ The gateway accepted the test event.",
+          `- Test ID: ${testID}`,
+          "- Check the Backeer application for the notification.",
+        ].join("\n")
       } else if (subcommand === "update-check") {
         const update = await updateChecker.check({ force: true })
         message = [
@@ -238,7 +252,7 @@ export function createBackeerCommandHandler({
         message = helpMessage()
       }
     } catch (error) {
-      reporter.error("Access token could not be updated", error)
+      reporter.error("Backeer command failed", error)
       message = [
         "## Backeer command failed",
         "",

package/src/updates.js

@@ -1,4 +1,4 @@
-export const PLUGIN_VERSION = "0.2.0"
+export const PLUGIN_VERSION = "0.2.1"
 
 const PACKAGE_NAME = "backeer-opencode"
 const NPM_REGISTRY_URL = "https://registry.npmjs.org"