@phystack/device-simulator 6.3.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @phystack/device-simulator
+
+## 6.3.0
+
+### Patch Changes
+
+- [#556](https://github.com/phystack/ps-platform/pull/556) [`4433273`](https://github.com/phystack/ps-platform/commit/4433273be94e88b8843aec6261cdb1e79936dc26) Thanks [@hassellof](https://github.com/hassellof)! - Ship `@phystack/device-simulator` as a published npm package and build a per-target standalone `phy-simulator` Bun binary for each developer platform.
+
+  The package was extracted from `tools/cli` but never wired into the publish pipeline, so a published `@phystack/cli` (which imports it via `workspace:*`) could not resolve it. It is now registered in the Changesets fixed group and the root `ci:build-packages`/`ci:publish-packages` scripts so the library is versioned and published like the other shared packages.
+
+  In addition, `scripts/build-device-binaries.sh` and `scripts/publish-device-binaries.js` now cross-compile `phy-simulator` and publish per-platform binary subpackages (`@phystack/phy-simulator-<platform>`) for the same darwin/linux/windows/musl matrix as the `phy` CLI, mirroring the existing device-binary publish flow in `deploy-device-apps.yml`.
+
+- Updated dependencies []:
+  - @phystack/hub-device@6.3.0

package/build-binary.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+VERSION=$(node -p "require('./package.json').version")
+
+# Args: [target] [outfile]
+#   target  — full Bun cross-compile target (e.g. bun-linux-x64,
+#             bun-linux-arm64, bun-darwin-x64, bun-darwin-arm64,
+#             bun-windows-x64). Defaults to the host target (no --target).
+#   outfile — output binary path. Defaults to "phy-simulator"
+#             ("phy-simulator.exe" when target is a Windows one).
+TARGET="${1:-}"
+
+DEFAULT_OUTFILE="phy-simulator"
+if [[ "$TARGET" == bun-windows-* ]]; then
+  DEFAULT_OUTFILE="phy-simulator.exe"
+fi
+OUTFILE="${2:-$DEFAULT_OUTFILE}"
+
+TARGET_ARGS=()
+if [[ -n "$TARGET" ]]; then
+  TARGET_ARGS+=("--target=${TARGET}")
+fi
+
+bun build --compile --minify \
+  --no-compile-autoload-dotenv \
+  --define '__PKG_VERSION__="'"$VERSION"'"' \
+  ${TARGET_ARGS[@]+"${TARGET_ARGS[@]}"} \
+  ./src/index.ts --outfile "$OUTFILE"
+
+# macOS AMFI SIGKILLs arm64 Mach-Os that lack a valid signature. Bun's
+# cross-compile on Linux already emits ad-hoc-signed darwin binaries, but
+# a local macOS host build may not — force a fresh ad-hoc signature so the
+# resulting binary is runnable on the same machine that built it.
+if [[ "$(uname -s)" == "Darwin" && "$(file "$OUTFILE")" == *Mach-O* ]]; then
+  codesign --remove-signature "$OUTFILE" 2>/dev/null || true
+  codesign --force --sign - "$OUTFILE"
+fi

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const utils_1 = require("./utils");
+const start_1 = __importDefault(require("./commands/start"));
+const run_1 = __importDefault(require("./commands/run"));
+const list_1 = __importDefault(require("./commands/list"));
+const remove_1 = __importDefault(require("./commands/remove"));
+const program = new commander_1.Command();
+program.version((0, utils_1.getPackageVersion)());
+program.description("Local device simulator for app development");
+program
+    .command("start")
+    .description("Start the local simulator server")
+    .option("-p, --port <port>", "Port to listen on", "55000")
+    .option("--connect <name>", "Connect to phyhub as a provisioned device")
+    .action((0, utils_1.handleError)(start_1.default));
+program
+    .command("run <path>")
+    .description("Run an app connected to the simulator (reconciles twin, spawns dev server)")
+    .option("--type <type>", "Override app type detection (screen or edge)")
+    .option("--dev-command <command>", "Override dev command (default: npm run dev)")
+    .option("--settings-dir <path>", "Settings directory path (default: src/settings)")
+    .action((0, utils_1.handleError)(run_1.default));
+program
+    .command("list")
+    .description("List all provisioned simulator devices")
+    .action(list_1.default);
+program
+    .command("remove <name>")
+    .description("Remove a saved simulator device")
+    .action(remove_1.default);
+program.parse(process.argv);
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@phystack/device-simulator",
+  "version": "6.3.0",
+  "description": "Standalone PhyStack device simulator for local app development.",
+  "main": "dist/command.js",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "phy-simulator": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "build:binary": "bash build-binary.sh",
+    "build:binary:target": "bash build-binary.sh",
+    "lint": "tsc --noEmit",
+    "test": "bun test src",
+    "test:ci": "bun test src"
+  },
+  "dependencies": {
+    "@phystack/hub-device": "6.3.0",
+    "chalk": "^3.0.0",
+    "commander": "^5.0.0",
+    "fs-extra": "^8.1.0",
+    "socket.io": "^4.7.5",
+    "socket.io-client": "^4.7.5",
+    "uuid": "^11.0.5"
+  },
+  "devDependencies": {
+    "@phystack/tsconfig": "5.0.0",
+    "@types/fs-extra": "^8.0.1",
+    "@types/node": "^20.14.9",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.5.2"
+  }
+}

package/src/__tests__/e2e/binary.e2e.test.ts

@@ -0,0 +1,394 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { spawn, spawnSync, type ChildProcess } from "child_process";
+import fs from "fs";
+import net from "net";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { io as socketIOClient, type Socket } from "socket.io-client";
+
+// --- Locate package root + the compiled binary ----------------------------
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../..",
+);
+const BINARY = path.join(PACKAGE_ROOT, "device-simulator-test");
+
+// Build the host binary once, here, if it isn't already present. This is the
+// crux of the e2e suite: every assertion below runs against the COMPILED Bun
+// binary (a child process), never against the TypeScript source.
+function ensureBinaryBuilt(): void {
+  if (fs.existsSync(BINARY)) return;
+  const result = spawnSync(
+    "bash",
+    ["build-binary.sh", "", "./device-simulator-test"],
+    {
+      cwd: PACKAGE_ROOT,
+      stdio: "pipe",
+      encoding: "utf8",
+    },
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `Failed to build the device-simulator test binary: ${result.stderr || result.stdout}`,
+    );
+  }
+}
+ensureBinaryBuilt();
+
+// Each e2e gets its own throwaway HOME so the child binary's config-paths
+// (CONFIG_DIR = $HOME/.config/phystack-cli) resolve under a temp dir — never the
+// real home. The binary reads HOME from its spawn env (process env, not the OS
+// user db, for the child). Tracked for afterAll cleanup.
+const tempHomes: string[] = [];
+function makeTempHome(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "sim-e2e-home-"));
+  tempHomes.push(dir);
+  return dir;
+}
+
+// Track spawned simulator processes so we always kill them, even on assertion
+// failure (cleanup is the sanctioned use of afterAll/finally per the test rules).
+const runningProcesses: ChildProcess[] = [];
+function trackProcess(child: ChildProcess): ChildProcess {
+  runningProcesses.push(child);
+  return child;
+}
+
+afterAll(() => {
+  for (const child of runningProcesses) {
+    if (!child.killed) {
+      try {
+        child.kill("SIGKILL");
+      } catch (error) {
+        console.error(
+          `Failed to kill simulator process ${child.pid}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+  }
+  for (const dir of tempHomes) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// --- Helpers ---------------------------------------------------------------
+
+function runBinary(
+  args: string[],
+  home: string,
+): { status: number | null; stdout: string; stderr: string } {
+  const result = spawnSync(BINARY, args, {
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+    encoding: "utf8",
+    timeout: 15000,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (address && typeof address === "object") {
+        const { port } = address;
+        server.close(() => resolve(port));
+      } else {
+        server.close(() =>
+          reject(new Error("Could not determine a free port")),
+        );
+      }
+    });
+  });
+}
+
+function waitForListening(port: number, timeoutMs = 10000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const attempt = () => {
+      const socket = net.connect(port, "127.0.0.1");
+      socket.on("connect", () => {
+        socket.end();
+        resolve();
+      });
+      socket.on("error", () => {
+        socket.destroy();
+        if (Date.now() > deadline) {
+          reject(
+            new Error(
+              `Simulator did not start listening on port ${port} in time`,
+            ),
+          );
+        } else {
+          setTimeout(attempt, 100);
+        }
+      });
+    };
+    attempt();
+  });
+}
+
+function startSimulator(port: number, home: string): ChildProcess {
+  const child = spawn(BINARY, ["start", "--port", String(port)], {
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+    stdio: "pipe",
+  });
+  return trackProcess(child);
+}
+
+function connectClient(port: number): Promise<Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = socketIOClient(`http://localhost:${port}`, {
+      reconnectionAttempts: 1,
+      timeout: 5000,
+    });
+    socket.on("connect", () => resolve(socket));
+    socket.on("connect_error", (error: Error) =>
+      reject(new Error(`Cannot connect to simulator: ${error.message}`)),
+    );
+    setTimeout(
+      () => reject(new Error("Timed out connecting to simulator")),
+      8000,
+    );
+  });
+}
+
+function emitSimulator(
+  socket: Socket,
+  payload: Record<string, unknown>,
+): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error("Timed out waiting for simulator ack")),
+      8000,
+    );
+    socket.emit("simulator", payload, (response: any) => {
+      clearTimeout(timer);
+      resolve(response);
+    });
+  });
+}
+
+// --- 1. CLI surface parity -------------------------------------------------
+
+describe("e2e: CLI surface (compiled binary)", () => {
+  test("--help lists every command", () => {
+    const home = makeTempHome();
+    const { stdout, status } = runBinary(["--help"], home);
+    expect(status).toBe(0);
+    expect(stdout).toContain("start");
+    expect(stdout).toContain("run");
+    expect(stdout).toContain("list");
+    expect(stdout).toContain("remove");
+    expect(stdout).toContain("Local device simulator for app development");
+  });
+
+  test("start --help shows the exact option strings and defaults", () => {
+    const home = makeTempHome();
+    const { stdout } = runBinary(["start", "--help"], home);
+    expect(stdout).toContain("-p, --port <port>");
+    expect(stdout).toContain('(default: "55000")');
+    expect(stdout).toContain("--connect <name>");
+  });
+
+  test("run --help shows the type / dev-command / settings-dir options", () => {
+    const home = makeTempHome();
+    const { stdout } = runBinary(["run", "--help"], home);
+    expect(stdout).toContain("--type <type>");
+    expect(stdout).toContain("--dev-command <command>");
+    expect(stdout).toContain("--settings-dir <path>");
+    expect(stdout).toMatch(/run \[options\] <path>/);
+  });
+
+  test("--version prints a semver", () => {
+    const home = makeTempHome();
+    const { stdout, status } = runBinary(["--version"], home);
+    expect(status).toBe(0);
+    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});
+
+// --- 2. list / remove against a temp HOME ---------------------------------
+
+describe("e2e: list / remove persistence contract (compiled binary)", () => {
+  test("seeded simulator shows in list, then remove deletes it", () => {
+    const home = makeTempHome();
+    const simulatorsDir = path.join(
+      home,
+      ".config",
+      "phystack-cli",
+      "simulators",
+    );
+    fs.mkdirSync(simulatorsDir, { recursive: true });
+
+    const seeded = {
+      name: "foo",
+      deviceId: "device-foo-123",
+      accessKey: "key-foo",
+      serialNumber: "SIM-FOO",
+      environment: "dev",
+      provisionedAt: "2026-06-16T12:00:00.000Z",
+      tenantId: "tenant-foo",
+    };
+    fs.writeFileSync(
+      path.join(simulatorsDir, "foo.json"),
+      JSON.stringify(seeded, null, 2),
+    );
+
+    const listed = runBinary(["list"], home);
+    expect(listed.status).toBe(0);
+    expect(listed.stdout).toContain("foo");
+    expect(listed.stdout).toContain("device-foo-123");
+
+    const removed = runBinary(["remove", "foo"], home);
+    expect(removed.status).toBe(0);
+    expect(removed.stdout).toContain('Removed simulator "foo".');
+    expect(fs.existsSync(path.join(simulatorsDir, "foo.json"))).toBe(false);
+
+    const emptyList = runBinary(["list"], home);
+    expect(emptyList.stdout).toContain("No provisioned simulators");
+  });
+
+  test("remove of a non-existent simulator exits non-zero", () => {
+    const home = makeTempHome();
+    const { status, stderr } = runBinary(["remove", "ghost"], home);
+    expect(status).not.toBe(0);
+    expect(stderr).toContain('Simulator "ghost" not found.');
+  });
+
+  test("list with no config prints the empty-state hint", () => {
+    const home = makeTempHome();
+    const { stdout, status } = runBinary(["list"], home);
+    expect(status).toBe(0);
+    expect(stdout).toContain("No provisioned simulators");
+  });
+});
+
+// --- 3. start server + socket.io handshake (the heart) --------------------
+
+describe("e2e: start server + socket.io protocol (compiled binary)", () => {
+  test("full twin handshake: status, create, get, report patch echo", async () => {
+    const home = makeTempHome();
+    const port = await getFreePort();
+    const child = startSimulator(port, home);
+    let client: Socket | undefined;
+
+    try {
+      await waitForListening(port);
+      client = await connectClient(port);
+
+      // ping → pong
+      expect(await emitSimulator(client, { method: "ping" })).toEqual({
+        status: "success",
+        message: "pong",
+      });
+
+      // getDeviceStatus reports the synthetic local Device twin. tenantId is the
+      // deterministic mockObjectId('local') the simulator derives at startup.
+      const status = await emitSimulator(client, { method: "getDeviceStatus" });
+      expect(status.status).toBe("success");
+      expect(status.socketConnected).toBe(true);
+      expect(status.tenantId).toBe("25bf8e1a2393f1108d37029b");
+      expect(status.displayName).toBe("Local Simulator");
+      expect(status.twins.Device).toHaveLength(1);
+
+      // createInstanceTwin registers a Screen twin and echoes it back.
+      const created = await emitSimulator(client, {
+        method: "createInstanceTwin",
+        data: { type: "Screen", desiredProperties: { appName: "e2e-app" } },
+      });
+      expect(created.status).toBe("success");
+      const twinId = created.twin.id as string;
+      expect(twinId).toBeTruthy();
+      expect(created.twin.type).toBe("Screen");
+      expect(created.twin.properties.desired).toEqual({ appName: "e2e-app" });
+
+      // getTwinById round-trips the freshly created twin.
+      const fetched = await emitSimulator(client, {
+        method: "getTwinById",
+        data: { twinId },
+      });
+      expect(fetched.status).toBe("success");
+      expect(fetched.twin.id).toBe(twinId);
+
+      // Subscribe to the twin so the reported-property patch is echoed back as a
+      // twinMessage/twinUpdated to this socket.
+      const twinUpdate = new Promise<any>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("No twinUpdated received")),
+          8000,
+        );
+        client!.on("twinMessage", (message: any) => {
+          if (message?.method === "twinUpdated" && message?.twinId === twinId) {
+            clearTimeout(timer);
+            resolve(message);
+          }
+        });
+      });
+      await emitSimulator(client, { method: "twinSubscribe", twinId });
+
+      // reportScreenTwinProperties merges reported props and emits twinUpdated.
+      const reported = await emitSimulator(client, {
+        method: "reportScreenTwinProperties",
+        twinId,
+        data: { online: true },
+      });
+      expect(reported.status).toBe("success");
+      expect(reported.twin.properties.reported).toEqual({ online: true });
+
+      // The simulator pushed the update back over the socket (twinMessage).
+      const echoed = await twinUpdate;
+      expect(echoed.data.id).toBe(twinId);
+      expect(echoed.data.properties.reported).toEqual({ online: true });
+
+      // Unknown method → structured error.
+      expect(await emitSimulator(client, { method: "bogusMethod" })).toEqual({
+        status: "error",
+        message: "Unknown method: bogusMethod",
+      });
+    } finally {
+      if (client) client.disconnect();
+      child.kill("SIGTERM");
+    }
+  });
+
+  test("start persists the device identity under the temp HOME (not the real home)", async () => {
+    const home = makeTempHome();
+    const port = await getFreePort();
+    const child = startSimulator(port, home);
+
+    try {
+      await waitForListening(port);
+      const deviceConfigPath = path.join(
+        home,
+        ".config",
+        "phystack-cli",
+        "simulator",
+        "tenants",
+        "local",
+        "device.json",
+      );
+      // Give the start sequence a beat to flush the device config to disk.
+      const deadline = Date.now() + 5000;
+      while (!fs.existsSync(deviceConfigPath) && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      expect(fs.existsSync(deviceConfigPath)).toBe(true);
+      const config = JSON.parse(fs.readFileSync(deviceConfigPath, "utf8"));
+      expect(config.tenantId).toBe("25bf8e1a2393f1108d37029b");
+      expect(typeof config.deviceId).toBe("string");
+      expect(typeof config.deviceTwinId).toBe("string");
+    } finally {
+      child.kill("SIGTERM");
+    }
+  });
+});

package/src/__tests__/preload.ts

@@ -0,0 +1,44 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+// Bun runs every test file in a SINGLE process with a SHARED module registry.
+// config-paths.ts computes CONFIG_DIR from os.homedir() at import time, and
+// os.homedir() ignores process.env.HOME on macOS/Linux (it reads the OS user
+// database). If any test file imports config-paths (directly or transitively,
+// e.g. via commands/run -> utils/simulator-config) before an override is in
+// place, CONFIG_DIR locks onto the REAL ~/.config/phystack-cli and every later
+// override is too late — tests then read/write the user's real config.
+//
+// This preload runs BEFORE any test module is evaluated (wired via
+// bunfig.toml [test].preload), so it is the single, authoritative place to
+// redirect os.homedir() to a throwaway temp dir for the whole suite. Persistence
+// tests share this one config root; they use unique device/tenant/simulator
+// names so they don't collide.
+//
+// Exported so individual test files can reference the same root and assert
+// isolation.
+export const SUITE_TEST_HOME: string = fs.mkdtempSync(
+  path.join(os.tmpdir(), "ps-sim-suite-home-"),
+);
+
+const realHomedir = os.homedir;
+(os as { homedir: () => string }).homedir = () => SUITE_TEST_HOME;
+process.env.HOME = SUITE_TEST_HOME;
+process.env.USERPROFILE = SUITE_TEST_HOME;
+
+// Best-effort cleanup of the suite temp dir when the process exits. Restoring
+// the original homedir keeps any post-test tooling honest.
+process.on("exit", () => {
+  (os as { homedir: () => string }).homedir = realHomedir;
+  try {
+    fs.rmSync(SUITE_TEST_HOME, { recursive: true, force: true });
+  } catch (error) {
+    // Surface but don't fail the run — the temp dir is under os.tmpdir().
+    console.error(
+      `Failed to remove suite test home ${SUITE_TEST_HOME}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+});

package/src/command.ts

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import { handleError } from "./utils";
+import start from "./commands/start";
+import run from "./commands/run";
+import simulatorList from "./commands/list";
+import simulatorRemove from "./commands/remove";
+
+// Re-export the simulator domain types so consumers (e.g. the legacy CLI's
+// utils/simulator-config) can resolve them from the package rather than the
+// now-removed tools/cli/src/simulator/ tree.
+export type {
+  SimulatorConfig,
+  DeviceConfig,
+  AppConfig,
+  TwinResponse,
+  EventPayload,
+} from "./simulator/types";
+export { AppTypeEnum, TwinTypeEnum } from "./simulator/types";
+export type { SimulatorConnectConfig } from "./utils/simulator-config";
+
+/**
+ * Build the `simulator` command tree as a standalone commander Command so the
+ * legacy CLI (tools/cli) can `program.addCommand(buildSimulatorCommand())` and
+ * preserve the `phy simulator …` surface unchanged.
+ */
+export function buildSimulatorCommand() {
+  const simulator = new Command("simulator");
+  simulator.description("Local device simulator for app development");
+
+  simulator
+    .command("start")
+    .description("Start the local simulator server")
+    .option("-p, --port <port>", "Port to listen on", "55000")
+    .option("--connect <name>", "Connect to phyhub as a provisioned device")
+    .action(handleError(start));
+
+  simulator
+    .command("run <path>")
+    .description(
+      "Run an app connected to the simulator (reconciles twin, spawns dev server)",
+    )
+    .option("--type <type>", "Override app type detection (screen or edge)")
+    .option(
+      "--dev-command <command>",
+      "Override dev command (default: npm run dev)",
+    )
+    .option(
+      "--settings-dir <path>",
+      "Settings directory path (default: src/settings)",
+    )
+    .action(handleError(run));
+
+  simulator
+    .command("list")
+    .description("List all provisioned simulator devices")
+    .action(simulatorList);
+
+  simulator
+    .command("remove <name>")
+    .description("Remove a saved simulator device")
+    .action(simulatorRemove);
+
+  return simulator;
+}
+
+export default buildSimulatorCommand;