peakflow-instance-control 0.1.1

package/README.md

@@ -0,0 +1,33 @@
+# peakflow-instance-control
+
+Instance-side terminal relay for Peakflow project environment sessions.
+
+The process connects to Peakflow ActionCable, receives terminal input commands, forwards them to tmux, and publishes terminal output snapshots back to Peakflow.
+
+## Install
+
+```bash
+npm install
+```
+
+## Run tests (Velocious)
+
+```bash
+npm test
+```
+
+## Run
+
+```bash
+node src/index.js \
+  --action-cable-url ws://example.com/cable \
+  --instance-control-token TOKEN \
+  --project-id PROJECT_ID \
+  --project-environment-instance-id INSTANCE_ID \
+  --project-environment-terminal-session-id SESSION_ID \
+  --tmux-session-name TMUX_SESSION
+```
+
+## 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

@@ -0,0 +1,23 @@
+{
+  "name": "peakflow-instance-control",
+  "version": "0.1.1",
+  "description": "Instance-side terminal relay for Peakflow project environment sessions",
+  "type": "module",
+  "bin": {
+    "peakflow-instance-control": "src/index.js"
+  },
+  "scripts": {
+    "release:patch": "bash scripts/release-patch.sh",
+    "start": "node src/index.js",
+    "test": "node scripts/velocious-cli.js test spec"
+  },
+  "dependencies": {
+    "@rails/actioncable": "^8.1.200"
+  },
+  "devDependencies": {
+    "glob": "^10.5.0",
+    "sqlite": "^5.1.1",
+    "sqlite3": "^5.1.7",
+    "velocious": "^1.0.213"
+  }
+}

package/peak_flow.yml

@@ -0,0 +1,8 @@
+environment:
+  NODE_ENV: test
+builds:
+  build_1:
+    name: Test
+    script:
+      - npm ci
+      - npm test

package/scripts/release-patch.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm version patch
+npm publish

package/scripts/velocious-cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises"
+import {glob} from "glob"
+
+/**
+ * Node 20 compatibility shim for Velocious CLI usage of fs.promises.glob.
+ * @returns {void}
+ */
+function ensureFsGlob() {
+  if (typeof fs.glob == "function") {
+    return
+  }
+
+  fs.glob = async function * fsGlobShim(pattern) {
+    const matches = await glob(pattern)
+
+    for (const match of matches) {
+      yield match
+    }
+  }
+}
+
+ensureFsGlob()
+await import("velocious/build/bin/velocious.js")

package/spec/keys-parser-spec.js

@@ -0,0 +1,22 @@
+import {describe, expect, it} from "velocious/build/src/testing/test.js"
+import {parseKeysChunks} from "../src/keys-parser.js"
+
+describe("parseKeysChunks", () => {
+  it("parses literals and enter", async () => {
+    const chunks = parseKeysChunks("echo hi\r")
+
+    expect(chunks).toEqual([
+      {type: "literal", value: "echo hi"},
+      {type: "key", value: "Enter"}
+    ])
+  })
+
+  it("parses arrow key sequence", async () => {
+    const chunks = parseKeysChunks("a\u001b[A")
+
+    expect(chunks).toEqual([
+      {type: "literal", value: "a"},
+      {type: "key", value: "Up"}
+    ])
+  })
+})

package/spec/tmux-client-spec.js

@@ -0,0 +1,48 @@
+import {describe, expect, it} from "velocious/build/src/testing/test.js"
+import TmuxClient from "../src/tmux-client.js"
+
+describe("TmuxClient", () => {
+  it("sends literal and enter chunks", async () => {
+    const calledArguments = []
+    const tmuxClient = new TmuxClient({
+      tmuxSessionName: "session-1",
+      executeTmuxCommand: async (argumentsList) => {
+        calledArguments.push(argumentsList)
+        return ""
+      }
+    })
+
+    await tmuxClient.sendKeys("echo hi\r")
+
+    expect(calledArguments).toEqual([
+      ["send-keys", "-t", "session-1", "-l", "--", "echo hi"],
+      ["send-keys", "-t", "session-1", "Enter"]
+    ])
+  })
+
+  it("creates tmux session when missing", async () => {
+    const calledArguments = []
+    let hasSessionAttempts = 0
+    const tmuxClient = new TmuxClient({
+      tmuxSessionName: "session-2",
+      executeTmuxCommand: async (argumentsList) => {
+        calledArguments.push(argumentsList)
+
+        if (argumentsList[0] == "has-session") {
+          hasSessionAttempts += 1
+          throw new Error("missing")
+        }
+
+        return ""
+      }
+    })
+
+    await tmuxClient.ensureSession()
+
+    expect(hasSessionAttempts).toEqual(1)
+    expect(calledArguments).toEqual([
+      ["has-session", "-t", "session-2"],
+      ["new-session", "-d", "-s", "session-2"]
+    ])
+  })
+})

package/src/cli-arguments.js

@@ -0,0 +1,60 @@
+/**
+ * Parse command line options for instance-control process.
+ * @param {string[]} argv
+ * @returns {{
+ *   actionCableUrl: string,
+ *   instanceControlToken: string,
+ *   projectEnvironmentInstanceId: string,
+ *   projectEnvironmentTerminalSessionId: string,
+ *   projectId: string,
+ *   tmuxSessionName: string
+ * }}
+ */
+export function parseCliArguments(argv) {
+  const args = [...argv]
+  const options = {}
+
+  while (args.length > 0) {
+    const argument = args.shift()
+
+    if (!argument.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${argument}`)
+    }
+
+    const optionName = argument.replace(/^--/, "")
+    const optionValue = args.shift()
+
+    if (!optionValue || optionValue.startsWith("--")) {
+      throw new Error(`Missing value for --${optionName}`)
+    }
+
+    options[optionName] = optionValue
+  }
+
+  validateRequiredOption({name: "action-cable-url", options})
+  validateRequiredOption({name: "instance-control-token", options})
+  validateRequiredOption({name: "project-environment-instance-id", options})
+  validateRequiredOption({name: "project-environment-terminal-session-id", options})
+  validateRequiredOption({name: "project-id", options})
+  validateRequiredOption({name: "tmux-session-name", options})
+
+  return {
+    actionCableUrl: options["action-cable-url"],
+    instanceControlToken: options["instance-control-token"],
+    projectEnvironmentInstanceId: options["project-environment-instance-id"],
+    projectEnvironmentTerminalSessionId: options["project-environment-terminal-session-id"],
+    projectId: options["project-id"],
+    tmuxSessionName: options["tmux-session-name"]
+  }
+}
+
+/**
+ * Validate required CLI option.
+ * @param {{name: string, options: Record<string, string>}} params
+ * @returns {void}
+ */
+function validateRequiredOption({name, options}) {
+  if (!options[name]) {
+    throw new Error(`Missing required option --${name}`)
+  }
+}

package/src/config/configuration.js

@@ -0,0 +1,23 @@
+import AsyncTrackedMultiConnection from "velocious/build/src/database/pool/async-tracked-multi-connection.js"
+import Configuration from "velocious/build/src/configuration.js"
+import NodeEnvironmentHandler from "velocious/build/src/environment-handlers/node.js"
+import SqliteDriver from "velocious/build/src/database/drivers/sqlite/index.js"
+
+export default new Configuration({
+  cookieSecret: "peakflow-instance-control-test-secret",
+  database: {
+    test: {
+      default: {
+        database: "/tmp/peakflow-instance-control-test",
+        driver: SqliteDriver,
+        poolType: AsyncTrackedMultiConnection,
+        type: "sqlite",
+        name: "peakflow-instance-control"
+      }
+    }
+  },
+  environmentHandler: new NodeEnvironmentHandler(),
+  locale: () => "en",
+  localeFallbacks: {en: ["en"]},
+  locales: ["en"]
+})

package/src/config/testing.js

@@ -0,0 +1,3 @@
+/** @returns {Promise<void>} */
+export default async function configureTesting() {
+}

package/src/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import {parseCliArguments} from "./cli-arguments.js"
+import TerminalRelay from "./terminal-relay.js"
+
+/** @returns {Promise<void>} */
+async function main() {
+  const options = parseCliArguments(process.argv.slice(2))
+  const relay = new TerminalRelay(options)
+
+  await relay.start()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/src/keys-parser.js

@@ -0,0 +1,66 @@
+const SPECIAL_CHARACTER_KEYS = {
+  "\r": "Enter",
+  "\t": "Tab",
+  "\u0003": "C-c",
+  "\u007F": "BSpace"
+}
+
+const SPECIAL_SEQUENCE_KEYS = {
+  "\u001b[A": "Up",
+  "\u001b[B": "Down",
+  "\u001b[C": "Right",
+  "\u001b[D": "Left"
+}
+
+/**
+ * Parse browser key stream into tmux chunks.
+ * @param {string} input
+ * @returns {{type: "key" | "literal", value: string}[]}
+ */
+export function parseKeysChunks(input) {
+  const normalizedInput = String(input || "")
+  const chunks = []
+  let literalChunk = ""
+  let index = 0
+
+  while (index < normalizedInput.length) {
+    const sequence = normalizedInput.slice(index, index + 3)
+    const specialSequenceKey = SPECIAL_SEQUENCE_KEYS[sequence]
+
+    if (specialSequenceKey) {
+      appendLiteralChunk({chunks, literalChunk})
+      literalChunk = ""
+      chunks.push({type: "key", value: specialSequenceKey})
+      index += 3
+      continue
+    }
+
+    const character = normalizedInput[index]
+    const specialCharacterKey = SPECIAL_CHARACTER_KEYS[character]
+
+    if (specialCharacterKey) {
+      appendLiteralChunk({chunks, literalChunk})
+      literalChunk = ""
+      chunks.push({type: "key", value: specialCharacterKey})
+    } else {
+      literalChunk += character
+    }
+
+    index += 1
+  }
+
+  appendLiteralChunk({chunks, literalChunk})
+
+  return chunks
+}
+
+/**
+ * Append literal chunk when non-empty.
+ * @param {{chunks: {type: "key" | "literal", value: string}[], literalChunk: string}} params
+ * @returns {void}
+ */
+function appendLiteralChunk({chunks, literalChunk}) {
+  if (literalChunk.length > 0) {
+    chunks.push({type: "literal", value: literalChunk})
+  }
+}

package/src/terminal-relay.js

@@ -0,0 +1,87 @@
+import {createConsumer} from "@rails/actioncable"
+import TmuxClient from "./tmux-client.js"
+
+/** Instance-side terminal relay over ActionCable. */
+export default class TerminalRelay {
+  /**
+   * Build relay with options.
+   * @param {{
+   *   actionCableUrl: string,
+   *   instanceControlToken: string,
+   *   projectEnvironmentInstanceId: string,
+   *   projectEnvironmentTerminalSessionId: string,
+   *   projectId: string,
+   *   tmuxSessionName: string
+   * }} options
+   */
+  constructor(options) {
+    this.options = options
+    this.tmuxClient = new TmuxClient({tmuxSessionName: options.tmuxSessionName})
+    this.consumer = createConsumer(options.actionCableUrl)
+  }
+
+  /** @returns {Promise<void>} */
+  async start() {
+    await this.tmuxClient.ensureSession()
+
+    this.subscription = this.consumer.subscriptions.create(
+      {
+        channel: "ProjectEnvironmentTerminalSessionsChannel",
+        instance_control: true,
+        instance_control_token: this.options.instanceControlToken,
+        project_environment_instance_id: this.options.projectEnvironmentInstanceId,
+        project_environment_terminal_session_id: this.options.projectEnvironmentTerminalSessionId,
+        project_id: this.options.projectId
+      },
+      {
+        connected: () => {
+          this.publishSnapshot().catch((error) => {
+            console.error(error)
+          })
+        },
+        received: (data) => {
+          this.onMessage(data).catch((error) => {
+            console.error(error)
+          })
+        },
+        rejected: () => {
+          throw new Error("ProjectEnvironmentTerminalSessionsChannel subscription rejected")
+        }
+      }
+    )
+  }
+
+  /**
+   * Handle command payload from ActionCable command stream.
+   * @param {Record<string, unknown>} data
+   * @returns {Promise<void>}
+   */
+  async onMessage(data) {
+    if (!data || typeof data != "object") {
+      return
+    }
+
+    if (data.type == "request_snapshot") {
+      await this.publishSnapshot()
+      return
+    }
+
+    if (data.type == "send_input") {
+      await this.tmuxClient.sendInput(data.input)
+      await this.publishSnapshot()
+      return
+    }
+
+    if (data.type == "send_keys") {
+      await this.tmuxClient.sendKeys(data.keys)
+      await this.publishSnapshot()
+    }
+  }
+
+  /** @returns {Promise<void>} */
+  async publishSnapshot() {
+    const payload = await this.tmuxClient.captureOutputPayload()
+
+    this.subscription.perform("publish_output", payload)
+  }
+}

package/src/tmux-client.js

@@ -0,0 +1,133 @@
+import {execFile} from "node:child_process"
+import {promisify} from "node:util"
+import {parseKeysChunks} from "./keys-parser.js"
+
+const execFileAsync = promisify(execFile)
+
+/** tmux command relay client. */
+export default class TmuxClient {
+  /**
+   * Build tmux client.
+   * @param {{tmuxSessionName?: string, executeTmuxCommand?: (argumentsList: string[]) => Promise<string>}} [options]
+   */
+  constructor({tmuxSessionName, executeTmuxCommand} = {}) {
+    this.tmuxSessionName = String(tmuxSessionName || "")
+    this.executeTmuxCommand = executeTmuxCommand || defaultExecuteTmuxCommand
+  }
+
+  /** @returns {Promise<void>} */
+  async ensureSession() {
+    await this.safeExecuteTmuxCommand(["has-session", "-t", this.tmuxSessionName])
+      .catch(async () => {
+        await this.safeExecuteTmuxCommand(["new-session", "-d", "-s", this.tmuxSessionName])
+      })
+  }
+
+  /**
+   * Send command string with Enter.
+   * @param {string} input
+   * @returns {Promise<void>}
+   */
+  async sendInput(input) {
+    const normalizedInput = String(input || "").trim()
+
+    if (normalizedInput == "") {
+      return
+    }
+
+    await this.safeExecuteTmuxCommand([
+      "send-keys",
+      "-t",
+      this.tmuxSessionName,
+      "--",
+      normalizedInput,
+      "Enter"
+    ])
+  }
+
+  /**
+   * Send raw key stream from browser terminal.
+   * @param {string} keys
+   * @returns {Promise<void>}
+   */
+  async sendKeys(keys) {
+    const normalizedKeys = String(keys || "")
+
+    if (normalizedKeys == "") {
+      return
+    }
+
+    const chunks = parseKeysChunks(normalizedKeys)
+
+    for (const chunk of chunks) {
+      if (chunk.type == "literal") {
+        await this.safeExecuteTmuxCommand([
+          "send-keys",
+          "-t",
+          this.tmuxSessionName,
+          "-l",
+          "--",
+          chunk.value
+        ])
+      } else {
+        await this.safeExecuteTmuxCommand([
+          "send-keys",
+          "-t",
+          this.tmuxSessionName,
+          chunk.value
+        ])
+      }
+    }
+  }
+
+  /** @returns {Promise<{terminal_cursor_col: null, terminal_cursor_row: null, terminal_output: string}>} */
+  async captureOutputPayload() {
+    const terminalOutput = await this.safeExecuteTmuxCommand([
+      "capture-pane",
+      "-pt",
+      this.tmuxSessionName,
+      "-S",
+      "-200"
+    ])
+
+    return {
+      terminal_cursor_col: null,
+      terminal_cursor_row: null,
+      terminal_output: terminalOutput
+    }
+  }
+
+  /**
+   * Execute tmux command and return stdout.
+   * @param {string[]} argumentsList
+   * @returns {Promise<string>}
+   */
+  async safeExecuteTmuxCommand(argumentsList) {
+    if (this.tmuxSessionName == "") {
+      throw new Error("Missing tmux session name")
+    }
+
+    return this.executeTmuxCommand(argumentsList)
+  }
+}
+
+/**
+ * Execute a tmux command with subprocess API.
+ * @param {string[]} argumentsList
+ * @returns {Promise<string>}
+ */
+async function defaultExecuteTmuxCommand(argumentsList) {
+  try {
+    const response = await execFileAsync("tmux", argumentsList)
+
+    return String(response.stdout || "")
+  } catch (error) {
+    const stderr = String(error.stderr || "")
+    const stdout = String(error.stdout || "")
+    const exitCode = error.code
+
+    throw new Error(
+      `tmux command failed exitCode=${exitCode} args=${JSON.stringify(argumentsList)} stdout=${JSON.stringify(stdout)} stderr=${JSON.stringify(stderr)}`
+    )
+  }
+}