peakflow-instance-control 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+- 2026-02-18: Added an npm authentication precheck to `npm run release:patch` so unauthenticated runs fail early with a clear `npm login` instruction instead of a publish 404.
+- 2026-02-18: Updated `npm run release:patch` to automatically run `npm login` when unauthenticated, then continue with publish only after a successful login.

package/README.md

@@ -16,11 +16,20 @@ npm install
 npm test
 ```
 
+## Release patch version
+
+```bash
+npm run release:patch
+```
+
+`release:patch` now checks npm authentication first and runs `npm login` automatically when needed before continuing.
+
 ## Run
 
 ```bash
 node src/index.js \
   --action-cable-url ws://example.com/cable \
+  --bug-report-auth-token BUG_REPORT_AUTH_TOKEN \
   --instance-control-token TOKEN \
   --project-id PROJECT_ID \
   --project-environment-instance-id INSTANCE_ID \
@@ -28,6 +37,12 @@ node src/index.js \
   --tmux-session-name TMUX_SESSION
 ```
 
+You can also provide the bug reporting auth token through:
+
+```bash
+PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN=BUG_REPORT_AUTH_TOKEN
+```
+
 ## Channel contract
 
 The process subscribes to `ProjectEnvironmentTerminalSessionsChannel` with `instance_control: true` and handles `request_snapshot`, `send_input`, and `send_keys` command payloads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peakflow-instance-control",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Instance-side terminal relay for Peakflow project environment sessions",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "test": "node scripts/velocious-cli.js test spec"
   },
   "dependencies": {
-    "@rails/actioncable": "^8.1.200"
+    "@rails/actioncable": "^8.1.200",
+    "peakflow-api": "^0.0.9"
   },
   "devDependencies": {
     "glob": "^10.5.0",

package/scripts/release-patch.sh

@@ -1,5 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+if ! npm whoami >/dev/null 2>&1; then
+  echo "You are not signed in to npm. Running 'npm login'..." >&2
+  npm login
+
+  if ! npm whoami >/dev/null 2>&1; then
+    echo "npm login did not complete successfully. Aborting release." >&2
+    exit 1
+  fi
+fi
+
 npm version patch
 npm publish

package/spec/cli-arguments-spec.js

@@ -0,0 +1,39 @@
+import {describe, expect, it} from "velocious/build/src/testing/test.js"
+import {parseCliArguments} from "../src/cli-arguments.js"
+
+describe("parseCliArguments", () => {
+  it("uses bug report auth token from environment when option is not passed", async () => {
+    process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN = "env-token"
+
+    const parsed = parseCliArguments([
+      "--action-cable-url", "ws://example.com/cable",
+      "--instance-control-token", "instance-token",
+      "--project-id", "project-id",
+      "--project-environment-instance-id", "instance-id",
+      "--project-environment-terminal-session-id", "session-id",
+      "--tmux-session-name", "tmux-name"
+    ])
+
+    expect(parsed.bugReportAuthToken).toEqual("env-token")
+
+    delete process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN
+  })
+
+  it("uses bug report auth token from cli option", async () => {
+    process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN = "env-token"
+
+    const parsed = parseCliArguments([
+      "--action-cable-url", "ws://example.com/cable",
+      "--bug-report-auth-token", "cli-token",
+      "--instance-control-token", "instance-token",
+      "--project-id", "project-id",
+      "--project-environment-instance-id", "instance-id",
+      "--project-environment-terminal-session-id", "session-id",
+      "--tmux-session-name", "tmux-name"
+    ])
+
+    expect(parsed.bugReportAuthToken).toEqual("cli-token")
+
+    delete process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN
+  })
+})

package/spec/terminal-relay-spec.js

@@ -0,0 +1,129 @@
+import {describe, expect, it} from "velocious/build/src/testing/test.js"
+import TerminalRelay from "../src/terminal-relay.js"
+
+/**
+ * @param {{captureOutputPayload?: () => Promise<{terminal_output: string}>}} [options]
+ * @returns {typeof import("../src/tmux-client.js").default}
+ */
+function buildTmuxClientClass(options = {}) {
+  return class FakeTmuxClient {
+    /** @returns {Promise<void>} */
+    async ensureSession() {
+    }
+
+    /** @returns {Promise<{terminal_output: string}>} */
+    async captureOutputPayload() {
+      if (options.captureOutputPayload) {
+        return options.captureOutputPayload()
+      }
+
+      return {terminal_output: "snapshot"}
+    }
+
+    /** @returns {Promise<void>} */
+    async sendInput() {
+    }
+
+    /** @returns {Promise<void>} */
+    async sendKeys() {
+    }
+  }
+}
+
+describe("TerminalRelay", () => {
+  it("reports connected callback errors", async () => {
+    const reportCalls = []
+    let callbacks = null
+    const relay = new TerminalRelay(
+      {
+        actionCableUrl: "ws://example.com/cable",
+        bugReportAuthToken: undefined,
+        instanceControlToken: "instance-token",
+        projectEnvironmentInstanceId: "instance-id",
+        projectEnvironmentTerminalSessionId: "session-id",
+        projectId: "project-id",
+        tmuxSessionName: "tmux-name"
+      },
+      {
+        bugReporter: {
+          reportError: async (options) => {
+            reportCalls.push(options)
+          }
+        },
+        TmuxClientClass: buildTmuxClientClass({
+          captureOutputPayload: async () => {
+            throw new Error("could not capture")
+          }
+        }),
+        createConsumerFunction: () => ({
+          subscriptions: {
+            create: (_identifier, subscriptionCallbacks) => {
+              callbacks = subscriptionCallbacks
+              return {perform: () => {}}
+            }
+          }
+        })
+      }
+    )
+    const originalConsoleError = console.error
+
+    console.error = () => {}
+    await relay.start()
+    callbacks.connected()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    console.error = originalConsoleError
+
+    expect(reportCalls.length).toEqual(1)
+    expect(reportCalls[0].context).toEqual("connected")
+    expect(reportCalls[0].error.message).toEqual("could not capture")
+  })
+
+  it("reports rejected subscriptions", async () => {
+    const reportCalls = []
+    let callbacks = null
+    const relay = new TerminalRelay(
+      {
+        actionCableUrl: "ws://example.com/cable",
+        bugReportAuthToken: undefined,
+        instanceControlToken: "instance-token",
+        projectEnvironmentInstanceId: "instance-id",
+        projectEnvironmentTerminalSessionId: "session-id",
+        projectId: "project-id",
+        tmuxSessionName: "tmux-name"
+      },
+      {
+        bugReporter: {
+          reportError: async (options) => {
+            reportCalls.push(options)
+          }
+        },
+        TmuxClientClass: buildTmuxClientClass(),
+        createConsumerFunction: () => ({
+          subscriptions: {
+            create: (_identifier, subscriptionCallbacks) => {
+              callbacks = subscriptionCallbacks
+              return {perform: () => {}}
+            }
+          }
+        })
+      }
+    )
+    const originalConsoleError = console.error
+    let raisedError = null
+
+    console.error = () => {}
+    await relay.start()
+    try {
+      callbacks.rejected()
+    } catch (error) {
+      raisedError = error
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    console.error = originalConsoleError
+
+    expect(raisedError.message).toEqual("ProjectEnvironmentTerminalSessionsChannel subscription rejected")
+    expect(reportCalls.length).toEqual(1)
+    expect(reportCalls[0].context).toEqual("rejected")
+    expect(reportCalls[0].error.message).toEqual("ProjectEnvironmentTerminalSessionsChannel subscription rejected")
+  })
+})

package/src/bug-reporter.js

@@ -0,0 +1,50 @@
+import {BugReporting} from "peakflow-api"
+
+/** Reports instance-control runtime errors to Peakflow. */
+export default class BugReporter {
+  /**
+   * @param {{bugReportAuthToken?: string}} options
+   */
+  constructor(options) {
+    this.options = options
+    this.bugReporting = this.buildBugReporting()
+  }
+
+  /**
+   * @param {{error: Error, context: string}} options
+   * @returns {Promise<void>}
+   */
+  async reportError(options) {
+    const {error, context} = options
+
+    if (!this.bugReporting) {
+      return
+    }
+
+    try {
+      await this.bugReporting.handleError({
+        error,
+        errorClass: error.name || "Error",
+        line: null,
+        file: null,
+        message: error.message,
+        url: null
+      })
+    } catch (reportError) {
+      console.error(`Could not report ${context} error to Peakflow`)
+      console.error(reportError)
+    }
+  }
+
+  /**
+   * @returns {BugReporting|undefined}
+   */
+  buildBugReporting() {
+    const authToken = this.options.bugReportAuthToken
+    if (!authToken) {
+      return undefined
+    }
+
+    return new BugReporting({authToken})
+  }
+}

package/src/cli-arguments.js

@@ -3,6 +3,7 @@
  * @param {string[]} argv
  * @returns {{
  *   actionCableUrl: string,
+ *   bugReportAuthToken: string|undefined,
  *   instanceControlToken: string,
  *   projectEnvironmentInstanceId: string,
  *   projectEnvironmentTerminalSessionId: string,
@@ -40,6 +41,7 @@ export function parseCliArguments(argv) {
 
   return {
     actionCableUrl: options["action-cable-url"],
+    bugReportAuthToken: options["bug-report-auth-token"] || process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN,
     instanceControlToken: options["instance-control-token"],
     projectEnvironmentInstanceId: options["project-environment-instance-id"],
     projectEnvironmentTerminalSessionId: options["project-environment-terminal-session-id"],

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import BugReporter from "./bug-reporter.js"
 import {parseCliArguments} from "./cli-arguments.js"
 import TerminalRelay from "./terminal-relay.js"
 
@@ -12,6 +13,27 @@ async function main() {
 }
 
 main().catch((error) => {
+  const bugReporter = new BugReporter({
+    bugReportAuthToken: bugReportAuthTokenFromArgv(process.argv.slice(2))
+  })
+
+  bugReporter.reportError({context: "startup", error}).catch((reportError) => {
+    console.error(reportError)
+  })
   console.error(error)
   process.exit(1)
 })
+
+/**
+ * @param {string[]} argv
+ * @returns {string|undefined}
+ */
+function bugReportAuthTokenFromArgv(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] == "--bug-report-auth-token") {
+      return argv[index + 1]
+    }
+  }
+
+  return process.env.PEAKFLOW_INSTANCE_CONTROL_BUG_REPORT_AUTH_TOKEN
+}

package/src/terminal-relay.js

@@ -1,4 +1,5 @@
 import {createConsumer} from "@rails/actioncable"
+import BugReporter from "./bug-reporter.js"
 import TmuxClient from "./tmux-client.js"
 
 /** Instance-side terminal relay over ActionCable. */
@@ -7,17 +8,24 @@ export default class TerminalRelay {
    * Build relay with options.
    * @param {{
    *   actionCableUrl: string,
+   *   bugReportAuthToken: string|undefined,
    *   instanceControlToken: string,
    *   projectEnvironmentInstanceId: string,
    *   projectEnvironmentTerminalSessionId: string,
    *   projectId: string,
    *   tmuxSessionName: string
    * }} options
+   * @param {{
+   *   bugReporter?: BugReporter,
+   *   createConsumerFunction?: (url: string) => ReturnType<typeof createConsumer>,
+   *   TmuxClientClass?: typeof TmuxClient
+   * }} [dependencies]
    */
-  constructor(options) {
+  constructor(options, dependencies = {}) {
     this.options = options
-    this.tmuxClient = new TmuxClient({tmuxSessionName: options.tmuxSessionName})
-    this.consumer = createConsumer(options.actionCableUrl)
+    this.bugReporter = dependencies.bugReporter || new BugReporter({bugReportAuthToken: options.bugReportAuthToken})
+    this.tmuxClient = new (dependencies.TmuxClientClass || TmuxClient)({tmuxSessionName: options.tmuxSessionName})
+    this.consumer = (dependencies.createConsumerFunction || createConsumer)(options.actionCableUrl)
   }
 
   /** @returns {Promise<void>} */
@@ -36,21 +44,37 @@ export default class TerminalRelay {
       {
         connected: () => {
           this.publishSnapshot().catch((error) => {
-            console.error(error)
+            this.logAndReportError({context: "connected", error})
           })
         },
         received: (data) => {
           this.onMessage(data).catch((error) => {
-            console.error(error)
+            this.logAndReportError({context: "received", error})
           })
         },
         rejected: () => {
-          throw new Error("ProjectEnvironmentTerminalSessionsChannel subscription rejected")
+          const error = new Error("ProjectEnvironmentTerminalSessionsChannel subscription rejected")
+
+          this.logAndReportError({context: "rejected", error})
+          throw error
         }
       }
     )
   }
 
+  /**
+   * @param {{context: string, error: Error}} options
+   * @returns {void}
+   */
+  logAndReportError(options) {
+    const {context, error} = options
+
+    console.error(error)
+    this.bugReporter.reportError({context, error}).catch((reportError) => {
+      console.error(reportError)
+    })
+  }
+
   /**
    * Handle command payload from ActionCable command stream.
    * @param {Record<string, unknown>} data