bunqueue-dashboard 1.0.1 → 1.0.3

package/README.md

@@ -32,13 +32,15 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 ![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
 ![Bun](https://img.shields.io/badge/Bun-1.4-000?logo=bun&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
-![Oxlint + Oxfmt](https://img.shields.io/badge/Oxc-Oxlint%20%2B%20Oxfmt-7C3AED)
+![Oxlint + Bun fmt](https://img.shields.io/badge/Tooling-Oxlint%20%2B%20Bun%20fmt-7C3AED)
 
 <br />
 
-<img src="docs/public/tour.gif" alt="A guided tour of the bunqueue dashboard, clicking through the overview, queues, jobs, the dead-letter queue, flows, the SQLite inspector, and the AI Copilot" width="900" />
+<a href="https://www.youtube.com/watch?v=1bQRFXGClcc" title="Watch the full bunqueue dashboard tour on YouTube"><img src="docs/public/video-tour.png" alt="Watch the narrated 4K tour of bunqueue dashboard on YouTube" width="900" /></a>
 
-<sub>A quick tour. <a href="https://egeominotti.github.io/bunqueue-dashboard/">Try it live →</a></sub>
+### [▶ Watch the full tour on YouTube](https://www.youtube.com/watch?v=1bQRFXGClcc)
+
+<sub>A narrated 4K walkthrough (7:45, English with subtitles) recorded against a real bunqueue server under live traffic. <a href="https://egeominotti.github.io/bunqueue-dashboard/">Or try the live demo →</a></sub>
 
 <br /><br />
 
@@ -134,7 +136,7 @@ contracts; it never patches Bunqueue internals.
 
 ## Quick start
 
-**Prerequisites:** [Bun](https://bun.sh) 1.4.2 and a reachable bunqueue server (or let the control
+**Prerequisites:** [Bun](https://bun.sh) 1.4.4 and a reachable bunqueue server (or let the control
 agent start one for you from the **Server** page).
 
 ### Run from npm (no clone)
@@ -261,20 +263,21 @@ target-pinned Flow, Workflow, Queue and Backup agent operations.
 | `bun start` | **Agent + dashboard together** (one-command dev) |
 | `bun dev` | Dashboard only (Vite dev server) |
 | `bun run agent` | Control agent only |
-| `bun run build` | Typecheck (`tsc --noEmit`) + production build → `dist/` |
+| `bun run build` | Native Bun typecheck + production build → `dist/` |
+| `bun run typecheck` | Native `bun check` for the frontend, agent/scripts, examples and browser tests |
 | `bun run preview` | Preview the production build |
 | `bun run lint` | Lint with Oxlint, including type-aware rules and the implicit-`any` parity guard |
-| `bun run format:check` | Check formatting with Oxfmt |
-| `bun run check` | Oxlint + Oxfmt validation (the CI gate) |
-| `bun run check:fix` | Apply safe Oxlint fixes, then format with Oxfmt |
+| `bun run format:check` | Check formatting with native `bun fmt --check` |
+| `bun run check` | Native typechecking, Oxlint and native formatting validation |
+| `bun run check:fix` | Apply safe Oxlint fixes, then format with native `bun fmt` |
 | `bun test` | Unit + agent-lifecycle tests |
 | `bun run test:e2e:tls` | Queue, Flow and Workflow over verified native TLS, including untrusted-certificate rejection |
-| `bun run test:e2e:upgrade` | Real npm Bunqueue 2.9.2 SQLite schema-35 → 2.9.4 schema-37 migration and retention semantics |
+| `bun run test:e2e:upgrade` | Real npm Bunqueue 2.9.2 SQLite schema-35 → 2.9.20 schema-37 migration and retention semantics |
 | `bun run test:e2e` | Real TLS, SQLite upgrade, Flow, Workflow, Queue SDK, and three-broker PostgreSQL runtime tests |
 | `bun run test:e2e:browser` | Production UI tests on Chromium, Firefox and WebKit |
 | `bun run test:e2e:browser:postgres-fleet` | Real UI operations across three PostgreSQL brokers (requires Docker and Chromium) |
 | `bun run quality` | Complete static, build, docs, coverage, runtime, package and dependency gate |
-| `bun run test:e2e:postgres-fleet` | Three authenticated Bunqueue 2.9.4 brokers + three agents sharing disposable PostgreSQL 18.6 |
+| `bun run test:e2e:postgres-fleet` | Three authenticated Bunqueue 2.9.20 brokers + three agents sharing disposable PostgreSQL 18.6 |
 
 ## Docker
 

package/agent/backup/routes.ts

@@ -190,18 +190,26 @@ function assertDatabaseSnapshot(value: unknown, current: DbStats): void {
     throw new Error('A database snapshot is required to authorize restore');
   }
   const expected = value as Record<string, unknown>;
-  const allowed = ['path', 'exists', 'size', 'walSize', 'shmSize', 'totalSize', 'mtimeMs'];
-  const unknown = Object.keys(expected).find((key) => !allowed.includes(key));
+  const allowed = ['path', 'exists', 'size', 'walSize', 'shmSize', 'totalSize', 'mtimeMs'] as const;
+  const unknown = Object.keys(expected).find((key) => !(allowed as readonly string[]).includes(key));
   if (unknown) throw new Error(`Unknown database snapshot option: ${unknown}`);
-  if (
-    expected.path !== current.path ||
-    expected.exists !== current.exists ||
-    expected.size !== current.size ||
-    expected.walSize !== current.walSize ||
-    expected.shmSize !== current.shmSize ||
-    expected.totalSize !== current.totalSize ||
-    expected.mtimeMs !== current.mtimeMs
-  ) {
-    throw new Error('Database changed after restore confirmation; reload status and confirm again');
+  // Compare what reflects the data. The -shm file is SQLite's shared-memory WAL
+  // index: it appears and disappears as connections open and close (the last one
+  // deletes it) without any write, so it, and the total that includes it, would
+  // reject valid confirmations. Writes still move the main file or the WAL.
+  const compared = ['path', 'exists', 'size', 'walSize', 'mtimeMs'] as const;
+  // Name every field that moved so a rejected restore is diagnosable.
+  const changed = compared
+    .filter((field) => expected[field] !== current[field])
+    .map((field) => `${field} ${shown(expected[field])} → ${shown(current[field])}`);
+  if (changed.length > 0) {
+    throw new Error(
+      `Database changed after restore confirmation (${changed.join(', ')}); reload status and confirm again`
+    );
   }
 }
+
+function shown(value: unknown): string {
+  const text = String(value);
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}

package/agent/manager/config.ts

@@ -1,3 +1,4 @@
+import manifest from '../../package.json';
 import type { ServerConfig } from './types';
 
 const CONFIG_KEYS = new Set<keyof ServerConfig>([
@@ -10,7 +11,7 @@ const CONFIG_KEYS = new Set<keyof ServerConfig>([
 
 export function defaultConfig(): ServerConfig {
   return {
-    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.4 start',
+    command: process.env.BUNQUEUE_START_CMD || `bunx bunqueue@${manifest.dependencies.bunqueue} start`,
     httpPort: Number(process.env.HTTP_PORT) || 6790,
     tcpPort: Number(process.env.TCP_PORT) || 6789,
     dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',

package/agent/server/handler.ts

@@ -65,7 +65,8 @@ export function createFetchHandler(
       return new Response(null, { status: 204, headers: corsHeaders(origin, allowedOrigins) });
     }
     const mutating = method === 'POST' || method === 'PUT';
-    const authRequired = requireTokenForAll || (mutating && Boolean(token));
+    const configurationRead = pathname === '/control/config' || pathname === '/control/status';
+    const authRequired = requireTokenForAll || ((mutating || configurationRead) && Boolean(token));
     if (authRequired && !tokenOk(request, token)) {
       return json({ ok: false, error: 'Unauthorized' }, 401, origin);
     }

package/agent/server/router.ts

@@ -123,12 +123,16 @@ export async function routeAgentRequest(
           return sqliteOnly('S3 backup', currentStorageMode);
         }
         return manager.withStoppedMaintenance('restoring a backup', async () => {
+          // Measure what the operator confirmed before our own cleanup: releasing
+          // the Workflow Engine's connection checkpoints the WAL, which changes the
+          // files without any other writer and would void a valid confirmation.
+          const confirmedDatabase = await manager.dbStats(restoreConfig.dataPath);
           await closeWorkflowRuntime(runtime);
           return executePreparedBackupRequest(
             prepared,
             restoreConfig,
             current.status === 'running',
-            await manager.dbStats(restoreConfig.dataPath),
+            confirmedDatabase,
             backupRunner,
             undefined,
             managedTargetPolicy
@@ -197,6 +201,7 @@ function isWorkflowRuntimeRoute(pathname: string, method: string): boolean {
   if (method !== 'POST') return false;
   return (
     [
+      '/workflows/runtime/initialize',
       '/workflows/runtime/reload',
       '/workflows/start',
       '/workflows/recover',

package/agent/server/types.ts

@@ -5,7 +5,7 @@ export interface AgentOptions {
   allowedOrigins: string[];
   /** DNS-rebinding defense; compared by hostname only. */
   allowedHosts?: string[];
-  /** On loopback, when set, changing requests must present this token. */
+  /** On loopback, when set, mutations and complete configuration reads require this token. */
   token?: string;
   /** Network exposure: require token on every non-OPTIONS request. */
   requireTokenForAll?: boolean;

package/agent/workflow/runtime.ts

@@ -29,10 +29,12 @@ export interface WorkflowRuntimeStatus {
   queueName?: string;
   concurrency?: number;
   error?: string;
+  needsInitialization?: boolean;
 }
 
 export interface WorkflowRuntimePort {
-  status(config: ServerConfig, activate?: boolean): Promise<WorkflowRuntimeStatus>;
+  status(config: ServerConfig, serverRunning?: boolean): Promise<WorkflowRuntimeStatus>;
+  initialize(config: ServerConfig): Promise<WorkflowRuntimeStatus>;
   reload(config: ServerConfig): Promise<WorkflowRuntimeStatus>;
   start(config: ServerConfig, workflowName: string, input?: unknown): Promise<unknown>;
   signal(config: ServerConfig, id: string, event: string, payload?: unknown): Promise<void>;
@@ -72,20 +74,32 @@ export class WorkflowRuntime implements WorkflowRuntimePort {
     private readonly createEngine: WorkflowEngineFactory = (options) => new Engine(options)
   ) {}
 
-  status(config: ServerConfig, activate = true): Promise<WorkflowRuntimeStatus> {
+  status(config: ServerConfig, serverRunning = true): Promise<WorkflowRuntimeStatus> {
     return this.serial(async () => {
       const modulePath = configuredWorkflowModule(config);
       try {
         if (!modulePath) {
-          await this.closeActive();
           return { configured: false, ready: false, workflowNames: [] };
         }
-        if (!activate) {
-          await this.closeActive();
+        if (!serverRunning) {
           return stoppedRuntimeStatus(config, modulePath);
         }
-        const active = await this.ensure(config);
-        return readyRuntimeStatus(active);
+        const active = this.active;
+        if (active?.closeFailure !== undefined) throw quarantinedRuntimeError(active);
+        const path = await realpath(modulePath);
+        const modified = (await stat(path)).mtimeMs;
+        const options = workflowRuntimeOptions(config);
+        if (active?.signature === workflowRuntimeSignature(config, path, modified, options)) {
+          return readyRuntimeStatus(active);
+        }
+        return {
+          configured: true,
+          ready: false,
+          needsInitialization: true,
+          moduleName: basename(modulePath),
+          workflowNames: [],
+          ...options,
+        };
       } catch (error) {
         const active = this.active;
         return {
@@ -101,6 +115,10 @@ export class WorkflowRuntime implements WorkflowRuntimePort {
     });
   }
 
+  initialize(config: ServerConfig): Promise<WorkflowRuntimeStatus> {
+    return this.serial(async () => readyRuntimeStatus(await this.ensure(config)));
+  }
+
   reload(config: ServerConfig): Promise<WorkflowRuntimeStatus> {
     return this.serial(async () => {
       await this.closeActive();

package/agent/workflow/runtimeRoutes.ts

@@ -49,6 +49,9 @@ export async function routeWorkflowRuntimeRequest(
     );
   }
   if (!serverRunning) throw new Error('Start the managed Bunqueue server before workflow control.');
+  if (pathname === '/workflows/runtime/initialize') {
+    return success(await admitted(true, ({ config: current }) => runtime.initialize(current)));
+  }
   if (pathname === '/workflows/runtime/reload') {
     return success(await admitted(true, ({ config: current }) => runtime.reload(current)));
   }
@@ -98,7 +101,7 @@ function isRuntimePath(pathname: string, method: string): boolean {
   if (method === 'GET') return pathname === '/workflows/runtime';
   if (method !== 'POST') return false;
   return (
-    ['/workflows/runtime/reload', '/workflows/start', '/workflows/recover', '/workflows/archive', '/workflows/cleanup'].includes(pathname) ||
+    ['/workflows/runtime/initialize', '/workflows/runtime/reload', '/workflows/start', '/workflows/recover', '/workflows/archive', '/workflows/cleanup'].includes(pathname) ||
     /^\/workflows\/[^/]+\/(signal|resume-compensation|abandon-compensation)$/.test(pathname)
   );
 }