@reset-framework/backend 1.2.2

package/README.md

@@ -0,0 +1,22 @@
+# @reset-framework/backend
+
+`@reset-framework/backend` provides the optional TypeScript sidecar runtime for Reset apps.
+
+Use it from an app-local backend entry such as `backend/src/index.ts`:
+
+```ts
+import { defineBackend } from "@reset-framework/backend"
+
+export default defineBackend(({ handle, process }) => {
+  handle("system.ping", async () => ({ ok: true }))
+
+  handle("git.version", async () => {
+    return process.run({
+      command: "git",
+      args: ["--version"]
+    })
+  })
+})
+```
+
+`reset-framework-cli` bundles this backend into the desktop app and the native runtime talks to it over a stdio protocol.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@reset-framework/backend",
+  "version": "1.2.2",
+  "type": "module",
+  "description": "Optional TypeScript sidecar backend runtime for Reset Framework apps.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,83 @@
+export type BackendHandler<TParams = unknown, TResult = unknown> = (
+  params: TParams,
+  context: BackendContext
+) => Promise<TResult> | TResult;
+
+export interface BackendProcessInfo {
+  id: string;
+  pid: number;
+  command: string;
+  args: string[];
+  cwd: string;
+  running: boolean;
+  startedAt: string;
+}
+
+export interface BackendProcessSpawnOptions {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  shell?: boolean;
+}
+
+export interface BackendProcessRunOptions extends BackendProcessSpawnOptions {
+  input?: string;
+  timeoutMs?: number;
+  maxBufferBytes?: number;
+}
+
+export interface BackendProcessRunResult {
+  command: string;
+  args: string[];
+  cwd: string;
+  exitCode: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  failed: boolean;
+}
+
+export interface BackendProcessApi {
+  spawn(options: BackendProcessSpawnOptions): Promise<BackendProcessInfo>;
+  run(options: BackendProcessRunOptions): Promise<BackendProcessRunResult>;
+  write(processId: string, data: string): Promise<{ written: boolean }>;
+  kill(
+    processId: string,
+    options?: { signal?: string }
+  ): Promise<{ killed: boolean }>;
+  list(): Promise<{ processes: BackendProcessInfo[] }>;
+}
+
+export interface BackendContext {
+  handle<TParams = unknown, TResult = unknown>(
+    method: string,
+    handler: BackendHandler<TParams, TResult>
+  ): void;
+  emit(eventName: string, payload?: unknown): void;
+  process: BackendProcessApi;
+}
+
+export interface BackendDefinition {
+  __resetBackend: true;
+  setup(context: BackendContext): Promise<void> | void;
+}
+
+export class BackendError extends Error {
+  code: string;
+  details?: unknown;
+  constructor(code: string, message: string, details?: unknown);
+}
+
+export function createBackendError(
+  code: string,
+  message: string,
+  details?: unknown
+): BackendError;
+
+export function defineBackend(
+  setup: BackendDefinition["setup"]
+): BackendDefinition;
+
+export function isBackendDefinition(value: unknown): value is BackendDefinition;

package/src/index.js

@@ -0,0 +1,29 @@
+export class BackendError extends Error {
+  constructor(code, message, details = undefined) {
+    super(message)
+    this.name = "BackendError"
+    this.code = typeof code === "string" && code.trim() !== "" ? code : "backend_error"
+    if (details !== undefined) {
+      this.details = details
+    }
+  }
+}
+
+export function createBackendError(code, message, details = undefined) {
+  return new BackendError(code, message, details)
+}
+
+export function defineBackend(setup) {
+  if (typeof setup !== "function") {
+    throw new TypeError("defineBackend requires a setup function.")
+  }
+
+  return Object.freeze({
+    __resetBackend: true,
+    setup
+  })
+}
+
+export function isBackendDefinition(value) {
+  return Boolean(value?.__resetBackend === true && typeof value?.setup === "function")
+}

package/src/runner.js

@@ -0,0 +1,558 @@
+import { spawn } from "node:child_process"
+import process from "node:process"
+import { createInterface } from "node:readline"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import util from "node:util"
+
+import { BackendError, isBackendDefinition } from "./index.js"
+
+const protocolVersion = "reset-backend.v1"
+
+function writeProtocolMessage(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`)
+}
+
+function writeStderrLine(prefix, args) {
+  const message = util.format(...args)
+  process.stderr.write(`${prefix}${message}\n`)
+}
+
+function installProtocolSafeConsole() {
+  const levels = {
+    log: "[reset-backend:log] ",
+    info: "[reset-backend:info] ",
+    debug: "[reset-backend:debug] ",
+    warn: "[reset-backend:warn] ",
+    error: "[reset-backend:error] "
+  }
+
+  for (const [name, prefix] of Object.entries(levels)) {
+    console[name] = (...args) => {
+      writeStderrLine(prefix, args)
+    }
+  }
+}
+
+function requireRecord(value, message) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BackendError("invalid_argument", message)
+  }
+
+  return value
+}
+
+function requireString(value, message) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new BackendError("invalid_argument", message)
+  }
+
+  return value
+}
+
+function optionalStringArray(value, message) {
+  if (value === undefined) {
+    return []
+  }
+
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new BackendError("invalid_argument", message)
+  }
+
+  return [...value]
+}
+
+function optionalRecordOfStrings(value, message) {
+  if (value === undefined) {
+    return {}
+  }
+
+  const record = requireRecord(value, message)
+  const normalized = {}
+
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry !== "string") {
+      throw new BackendError("invalid_argument", message)
+    }
+
+    normalized[key] = entry
+  }
+
+  return normalized
+}
+
+function serializeError(error) {
+  if (error instanceof BackendError) {
+    return {
+      code: error.code,
+      message: error.message,
+      details: error.details
+    }
+  }
+
+  if (error instanceof Error) {
+    return {
+      code: "internal_error",
+      message: error.message
+    }
+  }
+
+  return {
+    code: "internal_error",
+    message: typeof error === "string" ? error : "Unknown backend error"
+  }
+}
+
+function createProcessManager(emit) {
+  let nextId = 1
+  const processes = new Map()
+
+  function toInfo(state) {
+    return Object.freeze({
+      id: state.id,
+      pid: state.child.pid ?? 0,
+      command: state.command,
+      args: [...state.args],
+      cwd: state.cwd,
+      running: state.running,
+      startedAt: state.startedAt
+    })
+  }
+
+  function wireChildState(state) {
+    state.child.stdout?.on("data", (chunk) => {
+      const text = String(chunk)
+      emit("process.stdout", {
+        processId: state.id,
+        text
+      })
+    })
+
+    state.child.stderr?.on("data", (chunk) => {
+      const text = String(chunk)
+      emit("process.stderr", {
+        processId: state.id,
+        text
+      })
+    })
+
+    state.child.once("error", (error) => {
+      emit("process.error", {
+        processId: state.id,
+        message: error instanceof Error ? error.message : String(error)
+      })
+    })
+
+    state.child.once("exit", (code, signal) => {
+      state.running = false
+      emit("process.exit", {
+        processId: state.id,
+        exitCode: typeof code === "number" ? code : null,
+        signal: typeof signal === "string" ? signal : null
+      })
+    })
+  }
+
+  async function spawnProcess(options) {
+    const record = requireRecord(options, "process.spawn requires an options object")
+    const command = requireString(record.command, "process.spawn requires a non-empty 'command'")
+    const args = optionalStringArray(record.args, "process.spawn 'args' must be a string array")
+    const cwd =
+      record.cwd === undefined
+        ? process.cwd()
+        : requireString(record.cwd, "process.spawn 'cwd' must be a string")
+    const env = {
+      ...process.env,
+      ...optionalRecordOfStrings(record.env, "process.spawn 'env' must be a string map")
+    }
+    const shell = record.shell === true
+
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      shell,
+      stdio: ["pipe", "pipe", "pipe"]
+    })
+
+    const state = {
+      id: `proc_${nextId++}`,
+      child,
+      command,
+      args,
+      cwd,
+      startedAt: new Date().toISOString(),
+      running: true
+    }
+
+    processes.set(state.id, state)
+    wireChildState(state)
+
+    emit("process.started", {
+      processId: state.id,
+      pid: child.pid ?? 0,
+      command,
+      args,
+      cwd
+    })
+
+    return toInfo(state)
+  }
+
+  async function runProcess(options) {
+    const record = requireRecord(options, "process.run requires an options object")
+    const command = requireString(record.command, "process.run requires a non-empty 'command'")
+    const args = optionalStringArray(record.args, "process.run 'args' must be a string array")
+    const cwd =
+      record.cwd === undefined
+        ? process.cwd()
+        : requireString(record.cwd, "process.run 'cwd' must be a string")
+    const env = {
+      ...process.env,
+      ...optionalRecordOfStrings(record.env, "process.run 'env' must be a string map")
+    }
+    const shell = record.shell === true
+    const input =
+      record.input === undefined
+        ? null
+        : requireString(record.input, "process.run 'input' must be a string")
+    const timeoutMs =
+      record.timeoutMs === undefined
+        ? 0
+        : Number(record.timeoutMs)
+    const maxBufferBytes =
+      record.maxBufferBytes === undefined
+        ? 8 * 1024 * 1024
+        : Number(record.maxBufferBytes)
+
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      throw new BackendError("invalid_argument", "process.run 'timeoutMs' must be a non-negative number")
+    }
+
+    if (!Number.isFinite(maxBufferBytes) || maxBufferBytes <= 0) {
+      throw new BackendError("invalid_argument", "process.run 'maxBufferBytes' must be a positive number")
+    }
+
+    return await new Promise((resolve, reject) => {
+      const child = spawn(command, args, {
+        cwd,
+        env,
+        shell,
+        stdio: ["pipe", "pipe", "pipe"]
+      })
+
+      let stdout = ""
+      let stderr = ""
+      let finished = false
+      let timedOut = false
+      let timeout = null
+
+      const fail = (error) => {
+        if (finished) {
+          return
+        }
+
+        finished = true
+        if (timeout) {
+          clearTimeout(timeout)
+        }
+        reject(error)
+      }
+
+      const append = (currentValue, update, chunk) => {
+        const text = String(chunk)
+        const nextSize = Buffer.byteLength(currentValue(), "utf8") + Buffer.byteLength(text, "utf8")
+        if (nextSize > maxBufferBytes) {
+          fail(new BackendError("max_buffer_exceeded", "process.run exceeded its output buffer limit", {
+            maxBufferBytes
+          }))
+          child.kill("SIGKILL")
+          return
+        }
+
+        update(currentValue() + text)
+      }
+
+      child.stdout?.on("data", (chunk) => append(() => stdout, (next) => { stdout = next }, chunk))
+      child.stderr?.on("data", (chunk) => append(() => stderr, (next) => { stderr = next }, chunk))
+      child.once("error", fail)
+      child.once("exit", (code, signal) => {
+        if (finished) {
+          return
+        }
+
+        finished = true
+        if (timeout) {
+          clearTimeout(timeout)
+        }
+
+        resolve({
+          command,
+          args,
+          cwd,
+          exitCode: typeof code === "number" ? code : null,
+          signal: typeof signal === "string" ? signal : null,
+          stdout,
+          stderr,
+          timedOut,
+          failed: timedOut || code !== 0
+        })
+      })
+
+      if (input !== null) {
+        child.stdin?.write(input)
+      }
+      child.stdin?.end()
+
+      if (timeoutMs > 0) {
+        timeout = setTimeout(() => {
+          timedOut = true
+          child.kill("SIGTERM")
+        }, timeoutMs)
+      }
+    })
+  }
+
+  async function writeToProcess(processId, data) {
+    const id = requireString(processId, "process.write requires a process id")
+    const text = requireString(data, "process.write requires string data")
+    const state = processes.get(id)
+
+    if (!state || !state.running || !state.child.stdin) {
+      throw new BackendError("process_not_found", `Backend process '${id}' is not running`)
+    }
+
+    state.child.stdin.write(text)
+    return { written: true }
+  }
+
+  async function killProcess(processId, options = {}) {
+    const id = requireString(processId, "process.kill requires a process id")
+    const state = processes.get(id)
+
+    if (!state || !state.running) {
+      return { killed: false }
+    }
+
+    const signal =
+      options?.signal === undefined
+        ? "SIGTERM"
+        : requireString(options.signal, "process.kill 'signal' must be a string")
+
+    state.child.kill(signal)
+    return { killed: true }
+  }
+
+  async function listProcesses() {
+    return {
+      processes: [...processes.values()].map((state) => toInfo(state))
+    }
+  }
+
+  async function disposeAll() {
+    for (const state of processes.values()) {
+      if (!state.running) {
+        continue
+      }
+
+      state.child.kill("SIGTERM")
+    }
+  }
+
+  return {
+    spawn: spawnProcess,
+    run: runProcess,
+    write: writeToProcess,
+    kill: killProcess,
+    list: listProcesses,
+    disposeAll
+  }
+}
+
+async function loadBackendEntry(entryFile, context) {
+  const moduleUrl = pathToFileURL(path.resolve(entryFile)).href
+  const loaded = await import(moduleUrl)
+  const candidate = loaded.default ?? loaded.backend ?? loaded
+
+  if (typeof candidate === "function") {
+    await candidate(context)
+    return
+  }
+
+  if (isBackendDefinition(candidate)) {
+    await candidate.setup(context)
+    return
+  }
+
+  if (candidate && typeof candidate.setup === "function") {
+    await candidate.setup(context)
+    return
+  }
+
+  if (candidate && typeof candidate.handlers === "object" && candidate.handlers !== null) {
+    for (const [method, handler] of Object.entries(candidate.handlers)) {
+      context.handle(method, handler)
+    }
+    return
+  }
+
+  if (candidate && candidate !== loaded) {
+    throw new Error("Backend entry must export defineBackend(...), a setup function, or a handlers map.")
+  }
+}
+
+async function main() {
+  installProtocolSafeConsole()
+
+  const entryFile = process.argv[2]
+  if (!entryFile) {
+    throw new Error("Missing backend entry file argument.")
+  }
+
+  const handlers = new Map()
+
+  const emit = (event, payload = null) => {
+    const eventName = requireString(event, "Backend event name must be a non-empty string")
+    writeProtocolMessage({
+      type: "event",
+      event: eventName,
+      payload
+    })
+  }
+
+  const processApi = createProcessManager(emit)
+
+  const context = Object.freeze({
+    handle(method, handler) {
+      const methodName = requireString(method, "Backend method name must be a non-empty string")
+      if (typeof handler !== "function") {
+        throw new TypeError(`Backend handler for '${methodName}' must be a function.`)
+      }
+      if (handlers.has(methodName)) {
+        throw new Error(`Backend method already registered: ${methodName}`)
+      }
+
+      handlers.set(methodName, handler)
+    },
+    emit,
+    process: Object.freeze({
+      spawn(options) {
+        return processApi.spawn(options)
+      },
+      run(options) {
+        return processApi.run(options)
+      },
+      write(processId, data) {
+        return processApi.write(processId, data)
+      },
+      kill(processId, options) {
+        return processApi.kill(processId, options)
+      },
+      list() {
+        return processApi.list()
+      }
+    })
+  })
+
+  context.handle("process.spawn", (params) => processApi.spawn(params))
+  context.handle("process.run", (params) => processApi.run(params))
+  context.handle("process.write", (params) => {
+    const record = requireRecord(params, "process.write requires an options object")
+    return processApi.write(
+      requireString(record.processId, "process.write requires 'processId'"),
+      requireString(record.data, "process.write requires 'data'")
+    )
+  })
+  context.handle("process.kill", (params) => {
+    const record = requireRecord(params, "process.kill requires an options object")
+    return processApi.kill(
+      requireString(record.processId, "process.kill requires 'processId'"),
+      record.signal === undefined ? {} : { signal: record.signal }
+    )
+  })
+  context.handle("process.list", () => processApi.list())
+
+  await loadBackendEntry(entryFile, context)
+
+  writeProtocolMessage({
+    type: "ready",
+    protocol: protocolVersion,
+    methods: [...handlers.keys()].sort(),
+    runtime: {
+      name: process.release?.name ?? "node",
+      version: process.version,
+      platform: process.platform,
+      arch: process.arch
+    }
+  })
+
+  const input = createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity
+  })
+
+  process.once("SIGTERM", async () => {
+    await processApi.disposeAll()
+    process.exit(0)
+  })
+
+  input.on("line", async (line) => {
+    if (typeof line !== "string" || line.trim() === "") {
+      return
+    }
+
+    let message
+    try {
+      message = JSON.parse(line)
+    } catch {
+      writeStderrLine("[reset-backend:warn] ", ["Ignoring invalid protocol message"])
+      return
+    }
+
+    if (message?.type !== "invoke" || typeof message?.id !== "number") {
+      return
+    }
+
+    const method = typeof message.method === "string" ? message.method : ""
+    const handler = handlers.get(method)
+    if (!handler) {
+      writeProtocolMessage({
+        type: "response",
+        id: message.id,
+        ok: false,
+        error: {
+          code: "backend_method_not_found",
+          message: `Unknown backend method: ${method}`
+        }
+      })
+      return
+    }
+
+    try {
+      const result = await handler(message.params, context)
+      writeProtocolMessage({
+        type: "response",
+        id: message.id,
+        ok: true,
+        result
+      })
+    } catch (error) {
+      writeProtocolMessage({
+        type: "response",
+        id: message.id,
+        ok: false,
+        error: serializeError(error)
+      })
+    }
+  })
+
+  input.once("close", async () => {
+    await processApi.disposeAll()
+    process.exit(0)
+  })
+}
+
+main().catch((error) => {
+  const serialized = serializeError(error)
+  writeStderrLine("[reset-backend:fatal] ", [serialized.message])
+  process.exit(1)
+})