beads-ui 0.4.0 → 0.4.2

package/CHANGES.md

@@ -1,5 +1,19 @@
 # Changes
 
+## 0.4.2
+
+- [`66e31ff`](https://github.com/mantoni/beads-ui/commit/66e31ff0e053f3691657ce1175fd9b02155ca699)
+  Fix pre-bundled app: Check for bundle instead of NODE_ENV (Maximilian Antoni)
+
+_Released by [Maximilian Antoni](https://github.com/mantoni) on 2025-10-29._
+
+## 0.4.1
+
+- [`03d3477`](https://github.com/mantoni/beads-ui/commit/03d34774cd35bf03d142d2869633327cbe4902bd)
+  Fix missing protocol.js in bundle
+
+_Released by [Maximilian Antoni](https://github.com/mantoni) on 2025-10-29._
+
 ## 0.4.0
 
 - [`20a787c`](https://github.com/mantoni/beads-ui/commit/20a787c248225b4959b18b703894daf483f380b6)

package/app/protocol.js

@@ -0,0 +1,206 @@
+/**
+ * Protocol definitions for beads-ui WebSocket communication.
+ *
+ * Conventions
+ * - All messages are JSON objects.
+ * - Client → Server uses RequestEnvelope.
+ * - Server → Client uses ReplyEnvelope.
+ * - Every request is correlated by `id` in replies.
+ * - Server can also send unsolicited events (e.g., subscription `snapshot`).
+ */
+
+/** @typedef {'list-issues'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'|'subscribe-list'|'unsubscribe-list'|'snapshot'|'upsert'|'delete'} MessageType */
+
+/**
+ * @typedef {Object} RequestEnvelope
+ * @property {string} id - Unique id to correlate request/response.
+ * @property {MessageType} type - Message type.
+ * @property {unknown} [payload] - Message payload.
+ */
+
+/**
+ * @typedef {Object} ErrorObject
+ * @property {string} code - Stable error code.
+ * @property {string} message - Human-readable message.
+ * @property {unknown} [details] - Optional extra info for debugging.
+ */
+
+/**
+ * @typedef {Object} ReplyEnvelope
+ * @property {string} id - Correlates to the originating request.
+ * @property {boolean} ok - True when request succeeded; false on error.
+ * @property {MessageType} type - Echoes request type (or event type).
+ * @property {unknown} [payload] - Response payload.
+ * @property {ErrorObject} [error] - Present when ok=false.
+ */
+
+/** @type {MessageType[]} */
+export const MESSAGE_TYPES = /** @type {const} */ ([
+  'list-issues',
+  'update-status',
+  'edit-text',
+  'update-priority',
+  'create-issue',
+  'list-ready',
+  'dep-add',
+  'dep-remove',
+  'epic-status',
+  'update-assignee',
+  'label-add',
+  'label-remove',
+  'subscribe-list',
+  'unsubscribe-list',
+  // vNext per-subscription full-issue push events
+  'snapshot',
+  'upsert',
+  'delete'
+]);
+
+/**
+ * Generate a lexically sortable request id.
+ *
+ * @returns {string}
+ */
+export function nextId() {
+  const now = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${now}-${rand}`;
+}
+
+/**
+ * Create a request envelope.
+ *
+ * @param {MessageType} type - Message type.
+ * @param {unknown} [payload] - Message payload.
+ * @param {string} [id] - Optional id; generated if omitted.
+ * @returns {RequestEnvelope}
+ */
+export function makeRequest(type, payload, id = nextId()) {
+  return { id, type, payload };
+}
+
+/**
+ * Create a successful reply envelope for a given request.
+ *
+ * @param {RequestEnvelope} req - Original request.
+ * @param {unknown} [payload] - Reply payload.
+ * @returns {ReplyEnvelope}
+ */
+export function makeOk(req, payload) {
+  return { id: req.id, ok: true, type: req.type, payload };
+}
+
+/**
+ * Create an error reply envelope for a given request.
+ *
+ * @param {RequestEnvelope} req - Original request.
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} [details]
+ * @returns {ReplyEnvelope}
+ */
+export function makeError(req, code, message, details) {
+  return {
+    id: req.id,
+    ok: false,
+    type: req.type,
+    error: { code, message, details }
+  };
+}
+
+/**
+ * Check if a value is a plain object.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Type guard for MessageType values.
+ *
+ * @param {unknown} value
+ * @returns {value is MessageType}
+ */
+export function isMessageType(value) {
+  return (
+    typeof value === 'string' &&
+    MESSAGE_TYPES.includes(/** @type {MessageType} */ (value))
+  );
+}
+
+/**
+ * Type guard for RequestEnvelope.
+ *
+ * @param {unknown} value
+ * @returns {value is RequestEnvelope}
+ */
+export function isRequest(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return (
+    typeof value.id === 'string' &&
+    typeof value.type === 'string' &&
+    (value.payload === undefined || 'payload' in value)
+  );
+}
+
+/**
+ * Type guard for ReplyEnvelope.
+ *
+ * @param {unknown} value
+ * @returns {value is ReplyEnvelope}
+ */
+export function isReply(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (
+    typeof value.id !== 'string' ||
+    typeof value.ok !== 'boolean' ||
+    !isMessageType(value.type)
+  ) {
+    return false;
+  }
+  if (value.ok === false) {
+    const err = value.error;
+    if (
+      !isRecord(err) ||
+      typeof err.code !== 'string' ||
+      typeof err.message !== 'string'
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Normalize and validate an incoming JSON value as a RequestEnvelope.
+ * Throws a user-friendly error if invalid.
+ *
+ * @param {unknown} json
+ * @returns {RequestEnvelope}
+ */
+export function decodeRequest(json) {
+  if (!isRequest(json)) {
+    throw new Error('Invalid request envelope');
+  }
+  return json;
+}
+
+/**
+ * Normalize and validate an incoming JSON value as a ReplyEnvelope.
+ *
+ * @param {unknown} json
+ * @returns {ReplyEnvelope}
+ */
+export function decodeReply(json) {
+  if (!isReply(json)) {
+    throw new Error('Invalid reply envelope');
+  }
+  return json;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beads-ui",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Local UI for Beads — Collaborate on issues with your coding agent.",
   "keywords": [
     "agent",
@@ -29,7 +29,8 @@
     "preversion": "npm run all",
     "version": "changes --commits --footer",
     "postversion": "git push --follow-tags && npm publish",
-    "prepack": "NODE_ENV=production npm run build"
+    "prepack": "npm run build",
+    "postpack": "rm app/main.bundle.js app/main.bundle.js.map"
   },
   "dependencies": {
     "debug": "^4.4.3",
@@ -63,6 +64,7 @@
     "app/styles.css",
     "app/main.bundle.js",
     "app/main.bundle.js.map",
+    "app/protocol.js",
     "bin",
     "server",
     "CHANGES.md",

package/server/app.js

@@ -2,12 +2,13 @@
  * @import { Express, Request, Response } from 'express'
  */
 import express from 'express';
+import fs from 'node:fs';
 import path from 'node:path';
 
 /**
  * Create and configure the Express application.
  *
- * @param {{ host: string, port: number, env: string, app_dir: string, root_dir: string }} config - Server configuration.
+ * @param {{ host: string, port: number, app_dir: string, root_dir: string }} config - Server configuration.
  * @returns {Express} Configured Express app instance.
  */
 export function createApp(config) {
@@ -26,12 +27,13 @@ export function createApp(config) {
     res.status(200).send({ ok: true });
   });
 
-  // In development, support on-demand bundling for a smooth DX.
-  // In production, we expect `app/main.bundle.js` to be pre-built and served statically.
-  if (config.env !== 'production') {
+  if (
+    !fs.statSync(path.resolve(config.app_dir, 'main.bundle.js'), {
+      throwIfNoEntry: false
+    })
+  ) {
     /**
      * On-demand bundle for the browser using esbuild.
-     * Note: esbuild is loaded lazily so tests don't require it to be installed.
      *
      * @param {Request} _req
      * @param {Response} res

package/server/cli/daemon.js

@@ -256,6 +256,6 @@ export function printServerUrl() {
     `beads db   ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
   );
 
-  const { url, env } = getConfig();
-  console.log(`beads ui   listening on ${url} (${env})`);
+  const { url } = getConfig();
+  console.log(`beads ui   listening on ${url}`);
 }

package/server/config.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
  * (i.e., the current working directory) so DB resolution follows the
  * caller's context rather than the install location.
  *
- * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string, url: string }}
+ * @returns {{ host: string, port: number, app_dir: string, root_dir: string, url: string }}
  */
 export function getConfig() {
   const this_file = fileURLToPath(new URL(import.meta.url));
@@ -28,7 +28,6 @@ export function getConfig() {
   return {
     host: host_value,
     port: port_value,
-    env: process.env.NODE_ENV ? String(process.env.NODE_ENV) : 'development',
     app_dir: path.resolve(package_root, 'app'),
     root_dir,
     url: `http://${host_value}:${port_value}`

package/server/ws.js

@@ -4,10 +4,10 @@
  * @import { MessageType } from '../app/protocol.js'
  */
 import { WebSocketServer } from 'ws';
+import { isRequest, makeError, makeOk } from '../app/protocol.js';
 import { runBd, runBdJson } from './bd.js';
 import { fetchListForSubscription } from './list-adapters.js';
 import { debug } from './logging.js';
-import { isRequest, makeError, makeOk } from './protocol.js';
 import { keyOf, registry } from './subscriptions.js';
 import { validateSubscribeListPayload } from './validators.js';
 

package/server/protocol.js

@@ -1,3 +0,0 @@
-// Server-side access to protocol utilities and constants.
-// Import from the shared client definition to ensure a single source of truth.
-export * from '../app/protocol.js';