buzz-me-in 2.1.0 → 2.1.2-beta.0

package/README.md

@@ -2,6 +2,9 @@
 
 Apartment intercom to Apple HomeKit, bridged over Twilio.
 
+[![CI](https://img.shields.io/github/actions/workflow/status/atdr/buzz-me-in/ci.yml?style=flat-square&label=CI)](https://github.com/atdr/buzz-me-in/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/atdr/buzz-me-in?style=flat-square&label=coverage)](https://codecov.io/gh/atdr/buzz-me-in)
+
 A Raspberry Pi server that bridges an apartment intercom system into Apple HomeKit. When someone presses the intercom buzzer, your iPhone/HomePod receives a doorbell notification with a live camera tile. You can hear the caller, speak back, and unlock the door — all from the Home app or via Siri.
 
 ## Project docs

package/homekit.js

@@ -673,37 +673,68 @@ const cameraController = new CameraController({
 
 accessory.configureController(cameraController);
 
-accessory.publish({
-  username: config.hapUsername,
-  pincode: config.hapPincode,
-  port: config.hapPort,
-  category: Categories.VIDEO_DOORBELL,
-  advertiser: hap.MDNSAdvertiser.AVAHI,
-});
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
 
-logger.info('Accessory published', {
-  event: 'accessory-published',
-});
-// The setup QR encodes the pairing pincode, so only print it on an
-// interactive terminal — never into journald/log files.
-if (process.stdout.isTTY) {
-  logger.info('Accessory QR setup URI generated', {
-    event: 'accessory-qr-setup',
+let started = false;
+
+/**
+ * Put the accessory on the network and prepare the snapshot.
+ *
+ * Everything above this is in-memory construction; every side effect that
+ * reaches outside the process lives here. That split is deliberate: it lets
+ * server.js, a test, or the coverage run require this module without binding
+ * `HAP_PORT`, advertising a second accessory over Avahi alongside a live
+ * service, or spawning ffmpeg. server.js calls this from main().
+ *
+ * @returns {void}
+ */
+function start() {
+  if (started) {
+    logger.warn('Accessory start requested twice; ignoring', {
+      event: 'accessory-start-repeated',
+      reason: 'already-started',
+    });
+    return;
+  }
+  started = true;
+
+  accessory.publish({
+    username: config.hapUsername,
+    pincode: config.hapPincode,
+    port: config.hapPort,
+    category: Categories.VIDEO_DOORBELL,
+    advertiser: hap.MDNSAdvertiser.AVAHI,
   });
-  qrcode.generate(accessory.setupURI(), { small: true });
-} else {
-  logger.info('Pairing QR suppressed on non-interactive stdout; pair with HAP_PINCODE from .env', {
-    event: 'accessory-qr-suppressed',
-    reason: 'stdout-not-tty',
+
+  logger.info('Accessory published', {
+    event: 'accessory-published',
   });
-}
+  // The setup QR encodes the pairing pincode, so only print it on an
+  // interactive terminal — never into journald/log files.
+  if (process.stdout.isTTY) {
+    logger.info('Accessory QR setup URI generated', {
+      event: 'accessory-qr-setup',
+    });
+    qrcode.generate(accessory.setupURI(), { small: true });
+  } else {
+    logger.info(
+      'Pairing QR suppressed on non-interactive stdout; reprint it with buzz-me-in --qr',
+      {
+        event: 'accessory-qr-suppressed',
+        reason: 'stdout-not-tty',
+      }
+    );
+  }
 
-// Kick off snapshot generation asynchronously (non-blocking)
-initSnapshot().then(() =>
-  logger.info('Snapshot initialized', {
-    event: 'snapshot-ready',
-  })
-);
+  // Kick off snapshot generation asynchronously (non-blocking)
+  initSnapshot().then(() =>
+    logger.info('Snapshot initialized', {
+      event: 'snapshot-ready',
+    })
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Exports called by server.js
@@ -778,6 +809,9 @@ function setOnHapSessionStarted(handler) {
 function shutdown() {
   endHapSession();
   removeSdpDir();
+  // Nothing to tear down if start() never ran: unpublish() on an accessory
+  // that was never published has no HAP server or advertiser to stop.
+  if (!started) return;
   accessory.unpublish().catch((error) => {
     logger.error('Failed to unpublish HAP accessory during shutdown', {
       event: 'accessory-unpublish-failed',
@@ -788,6 +822,7 @@ function shutdown() {
 }
 
 module.exports = {
+  start,
   triggerDoorbell,
   setMulawPassthrough,
   clearMulawPassthrough,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.1.0",
+  "version": "2.1.2-beta.0",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "main": "server.js",
   "bin": {
@@ -22,6 +22,7 @@
     "check": "node --check server.js homekit.js twilio-api.js src/core/*.js",
     "test": "DOTENV_CONFIG_PATH=/dev/null node --test",
     "typecheck": "tsc --noEmit",
+    "coverage": "DOTENV_CONFIG_PATH=/dev/null node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-include='server.js' --test-coverage-include='homekit.js' --test-coverage-include='twilio-api.js' --require ./tests/helpers/coverage-preload.cjs --test-reporter=lcov --test-reporter-destination=lcov.info --test-reporter=spec --test-reporter-destination=stdout",
     "prepare": "husky || true"
   },
   "license": "MIT",

package/server.js

@@ -3,23 +3,29 @@
 'use strict';
 
 // CLI flags are handled before every other require, and moving this down breaks
-// them: requiring ./homekit calls accessory.publish() at module scope, which
-// would put a second accessory on the network alongside the running service,
-// and requiring ./src/core/config throws on any missing env var, which under
-// systemd lives in EnvironmentFile and so is absent from an interactive shell.
-// A read-only query must touch neither. tests/cli.test.cjs pins this ordering.
+// them: requiring ./src/core/config throws on any missing env var, which under
+// systemd lives in EnvironmentFile and so is absent from an interactive shell,
+// and requiring ./homekit pulls in that same config. A read-only query must
+// touch neither. tests/cli.test.cjs pins this ordering.
+//
+// The require.main guard keeps process.argv out of it when this file is loaded
+// as a library rather than run: a test or the coverage run would otherwise have
+// the test runner's own argv parsed as intercom flags. Everything below module
+// scope is likewise inert until main() runs.
 //
 // Writes are synchronous because process.exit() can truncate a pending async
 // write to a pipe.
-const cliFs = require('fs');
-const cliExit = require('./src/core/cli').run({
-  argv: process.argv.slice(2),
-  write: (text) => cliFs.writeSync(1, text),
-  writeErr: (text) => cliFs.writeSync(2, text),
-  isTTY: Boolean(process.stdout.isTTY),
-  cwd: process.cwd(),
-});
-if (cliExit !== null) process.exit(cliExit);
+if (require.main === module) {
+  const cliFs = require('fs');
+  const cliExit = require('./src/core/cli').run({
+    argv: process.argv.slice(2),
+    write: (text) => cliFs.writeSync(1, text),
+    writeErr: (text) => cliFs.writeSync(2, text),
+    isTTY: Boolean(process.stdout.isTTY),
+    cwd: process.cwd(),
+  });
+  if (cliExit !== null) process.exit(cliExit);
+}
 
 const http = require('http');
 const twilio = require('twilio');
@@ -369,12 +375,53 @@ function isAuthorizedForStatus(req) {
 // Start server
 // ---------------------------------------------------------------------------
 
-wsserver.listen(HTTP_SERVER_PORT, () => {
-  logger.info('Server listening', {
-    event: 'server-start',
-    port: HTTP_SERVER_PORT,
+/**
+ * Every side effect that reaches outside the process lives here: publishing the
+ * HomeKit accessory, binding the HTTP/WebSocket port, and installing the
+ * process-level signal and crash handlers. Module scope above only builds
+ * objects and registers in-process callbacks, so requiring this file from a
+ * test or the coverage run advertises nothing, binds nothing, and cannot
+ * install an uncaughtException handler that would swallow a test failure.
+ *
+ * homekit.start() comes first so the accessory is on the network before the
+ * port accepts a Twilio stream, which is the order the module-scope version
+ * produced and the order README's startup log example shows.
+ *
+ * @returns {void}
+ */
+function main() {
+  homekit.start();
+
+  wsserver.listen(HTTP_SERVER_PORT, () => {
+    logger.info('Server listening', {
+      event: 'server-start',
+      port: HTTP_SERVER_PORT,
+    });
   });
-});
+
+  process.on('SIGINT', () => beginShutdown('SIGINT'));
+  process.on('SIGTERM', () => beginShutdown('SIGTERM'));
+
+  // Exit on unexpected errors instead of continuing in an undefined state;
+  // systemd restarts the service.
+  process.on('uncaughtException', (err) => {
+    logger.error('Uncaught exception; exiting', {
+      event: 'uncaught-exception',
+      reason: 'uncaught-exception',
+      error: err,
+    });
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled promise rejection; exiting', {
+      event: 'unhandled-rejection',
+      reason: 'unhandled-rejection',
+      error: reason instanceof Error ? reason : new Error(String(reason)),
+    });
+    process.exit(1);
+  });
+}
 
 function beginShutdown(signal) {
   if (shuttingDown) return;
@@ -415,25 +462,15 @@ function beginShutdown(signal) {
   });
 }
 
-process.on('SIGINT', () => beginShutdown('SIGINT'));
-process.on('SIGTERM', () => beginShutdown('SIGTERM'));
-
-// Exit on unexpected errors instead of continuing in an undefined state;
-// systemd restarts the service.
-process.on('uncaughtException', (err) => {
-  logger.error('Uncaught exception; exiting', {
-    event: 'uncaught-exception',
-    reason: 'uncaught-exception',
-    error: err,
-  });
-  process.exit(1);
-});
-
-process.on('unhandledRejection', (reason) => {
-  logger.error('Unhandled promise rejection; exiting', {
-    event: 'unhandled-rejection',
-    reason: 'unhandled-rejection',
-    error: reason instanceof Error ? reason : new Error(String(reason)),
-  });
-  process.exit(1);
-});
+if (require.main === module) main();
+
+module.exports = {
+  main,
+  beginShutdown,
+  buildTwiml,
+  handleRequest,
+  isAuthorizedForStatus,
+  isValidTwilioRequest,
+  parseFormUrlEncoded,
+  readRequestBody,
+};

package/src/core/cli.js

@@ -10,8 +10,11 @@
 //
 // Nothing here starts a server, contacts HomeKit, or signals a running
 // instance. run() is called from server.js BEFORE any other require, because
-// requiring ./homekit publishes an accessory at module scope and requiring
-// ./src/core/config throws on a missing env var.
+// requiring ./src/core/config throws on a missing env var and ./homekit pulls
+// in that same config. Neither entry point acts on being required any more —
+// server.js starts from main() and homekit.js publishes from start() — so a
+// --qr run that reached them would no longer advertise a second accessory, but
+// it would still die on the missing env.
 
 const fs = require('fs');
 const path = require('path');