@phystack/device-simulator 6.3.0

package/src/commands/start.ts

@@ -0,0 +1,309 @@
+import chalk from "chalk";
+import crypto from "crypto";
+import { DeviceSimulator } from "../simulator";
+import { resolveApiUrl } from "../services/env";
+import { getAccessToken } from "../services/dev-token";
+import { getTenant } from "../utils/tenant-storage";
+import {
+  getSimulator,
+  saveSimulator,
+  type SimulatorConnectConfig,
+} from "../utils/simulator-config";
+
+async function resolveAuth(): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  const sessionCookie = process.env.PHYSTACK_SESSION_COOKIE;
+  const apiKey = process.env.PHYSTACK_API_KEY;
+
+  if (sessionCookie) {
+    headers["Cookie"] = `GRIDSESSION=${sessionCookie}`;
+  } else if (apiKey) {
+    headers["Authorization"] = `ApiKey ${apiKey}`;
+  } else {
+    // Read-only cached-token resolution (PHYSTACK_DEVELOPER_TOKEN, stored
+    // developer token, or the `phy login` device-token file). The interactive
+    // device-grant/refresh flows are unreachable here, so they stay in the
+    // legacy CLI and the standalone binary remains openid-client-free. The
+    // try/catch mirrors the original: ANY failure surfaces the same guidance.
+    try {
+      const token = getAccessToken();
+      if (!token) throw new Error("not logged in");
+      headers["Authorization"] = `Bearer ${token}`;
+    } catch {
+      throw new Error(
+        'No auth available. Set PHYSTACK_SESSION_COOKIE, PHYSTACK_API_KEY, or run "phy login".',
+      );
+    }
+  }
+  return headers;
+}
+
+async function provisionDevice(
+  name: string,
+  apiUrl: string,
+): Promise<SimulatorConnectConfig> {
+  const serialNumber = `SIM-${crypto.randomBytes(4).toString("hex")}`;
+  // CLI deployment env (LOCAL/DEV/QA/PROD), lowercased for the saved
+  // simulator config. Defaults to 'prod' when PHYSTACK_CLI_ENV is unset.
+  const environment = (process.env.PHYSTACK_CLI_ENV || "PROD").toLowerCase();
+  const spaceId = process.env.PHYSTACK_SPACE_ID || "";
+
+  // Tenant + phyhub URL resolution. Two well-defined modes:
+  //
+  //   (A) Env-override mode: BOTH PHYSTACK_TENANT_ID and
+  //       PHYSTACK_SIMULATOR_PHYHUB_URL set. Used by monorepo `make local`
+  //       (via .env.dev) and CI scripts. They're paired so we never silently
+  //       compute a bad URL when only TENANT_ID is set against a tenant
+  //       whose residency we don't know.
+  //
+  //   (B) Active-tenant mode: NEITHER env var set, falls back to the active
+  //       tenant from `phy tenant select`. Residency comes from
+  //       tenant.dataResidency; phyhubUrl is left undefined so hub-device
+  //       synthesizes it from residency at connect time. Standard
+  //       regular-user path.
+  //
+  // Hybrid: PHYSTACK_SIMULATOR_PHYHUB_URL alone is allowed when an active
+  // tenant exists — lets a user ad-hoc override the URL for one provisioning
+  // without also having to dig their tenant id out of tenant.json. Going the
+  // other way (TENANT_ID alone) is rejected because there's no safe way to
+  // pick a URL for an arbitrary tenant.
+  const envTenantId = process.env.PHYSTACK_TENANT_ID;
+  const envPhyhubUrl = process.env.PHYSTACK_SIMULATOR_PHYHUB_URL;
+
+  if (envTenantId && !envPhyhubUrl) {
+    throw new Error(
+      "PHYSTACK_TENANT_ID is set without PHYSTACK_SIMULATOR_PHYHUB_URL. " +
+        "These env vars are paired — supply both to override the active tenant " +
+        "(e.g. monorepo `make local` or CI flows), or unset PHYSTACK_TENANT_ID " +
+        "to use the active tenant from `phy tenant select`.",
+    );
+  }
+
+  const activeTenant = envTenantId ? null : await getTenant();
+  const tenantId = envTenantId || activeTenant?.id;
+
+  if (!tenantId) {
+    throw new Error(
+      "No tenant available. Either run `phy tenant select` first, or set both " +
+        "PHYSTACK_TENANT_ID and PHYSTACK_SIMULATOR_PHYHUB_URL.",
+    );
+  }
+
+  const provisionUrl = `${apiUrl}/2026-03/devices`;
+  console.log(chalk.cyan(`Provisioning "${name}" via ${provisionUrl}...`));
+
+  const headers = await resolveAuth();
+  const response = await fetch(provisionUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      tenantId,
+      displayName: name,
+      deviceSerial: serialNumber,
+      spaceId: spaceId || undefined,
+      env: environment === "local" ? "LOCAL" : undefined,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Device provisioning failed (${response.status}): ${text}`);
+  }
+
+  const data = (await response.json()) as any;
+  const deviceData = data.data || data;
+
+  const deviceId = deviceData.deviceId || deviceData.id || deviceData.uuid;
+  const accessKey = deviceData.accessKey;
+  if (!deviceId || !accessKey) {
+    throw new Error(
+      `Provisioning response missing required fields. Got: ${JSON.stringify(deviceData)}`,
+    );
+  }
+
+  // Residency drives the saved config's region hint. Active-tenant mode:
+  // tenant.dataResidency is the truth (LOCAL/DEV/QA/EU/US/AU/IN/UAE).
+  // Env-override mode: falls back to PHYSTACK_CLI_ENV uppercased, which is
+  // harmless because envPhyhubUrl will win at connect time regardless.
+  const dataResidency =
+    activeTenant?.dataResidency ||
+    (environment ? environment.toUpperCase() : undefined);
+
+  // phyhubUrl on the saved config: env override if provided (env-override
+  // mode, or the URL-only ad-hoc override). Otherwise undefined — hub-device
+  // synthesizes from dataResidency at connect time (LOCAL → localhost:14401,
+  // real regions → https://phyhub.${region}.omborigrid.net). Never derived
+  // from the provisioning response (phyhub's DeviceResponse doesn't carry
+  // phyhubUrl — see apps/phyhub/src/common/types/device.types.ts:129).
+  const config: SimulatorConnectConfig = {
+    name,
+    deviceId,
+    accessKey,
+    serialNumber,
+    phyhubUrl: envPhyhubUrl || undefined,
+    environment,
+    dataResidency,
+    provisionedAt: new Date().toISOString(),
+    tenantId: deviceData.tenantId || deviceData.organizationId || tenantId,
+    spaceId: deviceData.spaceId || spaceId,
+  };
+
+  saveSimulator(config);
+  console.log(chalk.green(`Device "${name}" provisioned: ${config.deviceId}`));
+  return config;
+}
+
+async function startConnected(name: string): Promise<void> {
+  let config = getSimulator(name);
+
+  if (!config) {
+    config = await provisionDevice(name, resolveApiUrl());
+  } else {
+    console.log(chalk.cyan(`Reconnecting "${name}" (${config.deviceId})...`));
+  }
+
+  const hubDeviceModule = (await import("@phystack/hub-device")).default;
+
+  // `region` drives hub-device's phyhub URL synthesis (LOCAL → localhost:14401,
+  // EU/US/AU/IN/UAE/DEV/QA → phyhub.{r}.omborigrid.net). Prefer the saved
+  // dataResidency (from the active tenant via `phy tenant select`); fall back
+  // to environment for back-compat with saved configs from before this field
+  // existed.
+  const region =
+    config.dataResidency ||
+    (config.environment ? config.environment.toUpperCase() : "PROD");
+
+  console.log(
+    chalk.cyan(
+      `Connecting (region=${region}${config.phyhubUrl ? `, phyhubUrl=${config.phyhubUrl}` : ", URL resolved by hub-device"})...`,
+    ),
+  );
+
+  // Pass storage namespace so node storage uses
+  // `~/.config/phystack-cli/hub-device/<name>/` instead of `/data/settings/phyhub`
+  // (the on-device PhyOS path, which doesn't exist / isn't writable on dev
+  // machines — caused EROFS on macOS).
+  const connectionStatus = await hubDeviceModule.connectToPhyHub(
+    config.environment === "local" ? "LOCAL" : "PROD",
+    "simulator",
+    {
+      deviceId: config.deviceId,
+      accessKey: config.accessKey,
+      deviceSerial: config.serialNumber,
+      phyhubUrl: config.phyhubUrl,
+      region,
+    },
+    `simulator-${name}`,
+  );
+
+  // `connectToPhyHub` returns `{ phyHub: HubDevice, deviceSerial }` — the
+  // outer wrapper has no `.emit` / `.connect`, so the inner instance is what
+  // we drive (mirrors apps/device-phyos/src/index.ts:534).
+  const phyHub = connectionStatus?.phyHub;
+  if (!phyHub) {
+    throw new Error(
+      `connectToPhyHub() returned no HubDevice instance for "${name}"`,
+    );
+  }
+
+  // The constructor inside connectToPhyHub does not open the socket. Must
+  // call .connect() before any authenticated emits are accepted.
+  await phyHub.connect();
+
+  // connectDevice() round-trips with phyhub, returning the device's full
+  // twin inventory. We need the Device-type twin's `id` (the instanceTwinId)
+  // for subsequent reportDeviceTwinProperties calls — without it, phyhub's
+  // emitAuth handler rejects the message.
+  let deviceTwinId: string | undefined;
+  phyHub.connectDevice((response: any) => {
+    if (response?.error) {
+      console.warn(chalk.yellow(`connectDevice rejected: ${response.error}`));
+      return;
+    }
+    const deviceTwin = response?.twins?.find(
+      (twin: any) => twin?.type === "Device",
+    );
+    if (deviceTwin?.id) {
+      deviceTwinId = deviceTwin.id;
+      console.log(
+        chalk.green(
+          `Device "${name}" connected to phyhub (twinId=${deviceTwinId})`,
+        ),
+      );
+    } else {
+      console.warn(
+        chalk.yellow(
+          `connectDevice() returned no Device-type twin — heartbeat will be skipped`,
+        ),
+      );
+    }
+  });
+
+  // Heartbeat every 30s. Uses the typed helper (not raw `.emit`), which
+  // routes through emitAuth so phyhub-side authorization runs. Drops the
+  // tick silently until the connectDevice callback supplies a twinId —
+  // same pattern as apps/example-cloud-app waiting for a Cloud twin.
+  const heartbeat = setInterval(() => {
+    if (!deviceTwinId) return;
+    phyHub.reportDeviceTwinProperties(
+      deviceTwinId,
+      {
+        time: {
+          current: Date.now(),
+          uptime: process.uptime(),
+          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        },
+      },
+      (response: any) => {
+        if (response?.error) {
+          console.warn(
+            chalk.yellow(
+              `reportDeviceTwinProperties rejected: ${response.error}`,
+            ),
+          );
+        }
+      },
+    );
+  }, 30_000);
+
+  const shutdown = () => {
+    clearInterval(heartbeat);
+    console.log(chalk.yellow(`\nDevice "${name}" disconnecting...`));
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise(() => {});
+}
+
+export default async (
+  options: { port?: string; connect?: string } = {},
+): Promise<void> => {
+  const port = parseInt(options.port || "55000", 10);
+
+  if (options.connect) {
+    return startConnected(options.connect);
+  }
+
+  // Offline mode (default)
+  const simulator = new DeviceSimulator(port);
+
+  const shutdown = async () => {
+    await simulator.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  try {
+    await simulator.start();
+  } catch (error: any) {
+    console.error(chalk.red(`Failed to start simulator: ${error.message}`));
+    process.exit(1);
+  }
+
+  await new Promise(() => {});
+};

package/src/index.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { getPackageVersion, handleError } from "./utils";
+import start from "./commands/start";
+import run from "./commands/run";
+import simulatorList from "./commands/list";
+import simulatorRemove from "./commands/remove";
+
+const program = new Command();
+program.version(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(handleError(start));
+
+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(handleError(run));
+
+program
+  .command("list")
+  .description("List all provisioned simulator devices")
+  .action(simulatorList);
+
+program
+  .command("remove <name>")
+  .description("Remove a saved simulator device")
+  .action(simulatorRemove);
+
+program.parse(process.argv);

package/src/services/__tests__/dev-token.test.ts

@@ -0,0 +1,156 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { SUITE_TEST_HOME } from "../../__tests__/preload";
+
+// dev-token transitively imports config-paths, which computes DEVELOPER_TOKEN_FILE
+// and the auth-file paths from os.homedir() at import time. The test preload
+// (bunfig.toml) redirects os.homedir() to SUITE_TEST_HOME before any module
+// evaluates — on macOS/Linux os.homedir() ignores process.env.HOME, so the
+// preload override is what keeps the real ~/.config/phystack-cli untouched.
+const TEST_HOME = SUITE_TEST_HOME;
+const CONFIG_ROOT = path.join(TEST_HOME, ".config", "phystack-cli");
+fs.mkdirSync(CONFIG_ROOT, { recursive: true });
+
+const { getAccessToken } = await import("../dev-token");
+
+const DEVELOPER_TOKEN_FILE = path.join(CONFIG_ROOT, "developer-token.json");
+
+// Snapshot the env keys we mutate so each test can reset to a clean slate via
+// the named helper below (no beforeEach; cleanup-only afterAll for the temp dir).
+const MANAGED_ENV_KEYS = [
+  "PHYSTACK_DEVELOPER_TOKEN",
+  "PHYSTACK_CLI_ENV",
+  "PHYSTACK_CLI_AUTH_FILE_PATH",
+] as const;
+
+function clearTokenSources(): void {
+  for (const key of MANAGED_ENV_KEYS) {
+    delete process.env[key];
+  }
+  // Remove any on-disk token artifacts between scenarios.
+  fs.rmSync(DEVELOPER_TOKEN_FILE, { force: true });
+  for (const authName of ["auth", "auth-local", "auth-dev", "auth-qa"]) {
+    fs.rmSync(path.join(CONFIG_ROOT, authName), { force: true });
+  }
+}
+
+afterAll(() => {
+  // The suite temp dir itself is cleaned by the preload's exit handler; here we
+  // only clear the token artifacts so they don't bleed into other suites that
+  // share the same config root.
+  clearTokenSources();
+});
+
+describe("getAccessToken — 3-source resolution order", () => {
+  test("config dir resolves under the temp HOME", () => {
+    expect(CONFIG_ROOT.startsWith(TEST_HOME)).toBe(true);
+  });
+
+  test("PHYSTACK_DEVELOPER_TOKEN env wins over everything else", () => {
+    clearTokenSources();
+    // Also write a developer-token.json and an auth file to prove env precedence.
+    fs.writeFileSync(
+      DEVELOPER_TOKEN_FILE,
+      JSON.stringify({ token: "from-file" }),
+    );
+    fs.writeFileSync(
+      path.join(CONFIG_ROOT, "auth"),
+      JSON.stringify({ access_token: "from-auth" }),
+    );
+    process.env.PHYSTACK_DEVELOPER_TOKEN = "  env-token  ";
+
+    // Trimmed.
+    expect(getAccessToken()).toBe("env-token");
+  });
+
+  test("empty/whitespace env token is ignored and falls through to the file", () => {
+    clearTokenSources();
+    process.env.PHYSTACK_DEVELOPER_TOKEN = "   ";
+    fs.writeFileSync(
+      DEVELOPER_TOKEN_FILE,
+      JSON.stringify({ token: "file-token" }),
+    );
+
+    expect(getAccessToken()).toBe("file-token");
+  });
+
+  test("developer-token.json `.token` is used when env is unset", () => {
+    clearTokenSources();
+    fs.writeFileSync(
+      DEVELOPER_TOKEN_FILE,
+      JSON.stringify({ token: "dev-file-token" }),
+    );
+
+    expect(getAccessToken()).toBe("dev-file-token");
+  });
+
+  test("falls back to the auth tokens file `.access_token` for the active env", () => {
+    clearTokenSources();
+    process.env.PHYSTACK_CLI_ENV = "QA";
+    // getAuthFilePath('QA') → <config>/auth-qa
+    fs.writeFileSync(
+      path.join(CONFIG_ROOT, "auth-qa"),
+      JSON.stringify({ access_token: "qa-access-token" }),
+    );
+
+    expect(getAccessToken()).toBe("qa-access-token");
+  });
+
+  test("default auth file (no PHYSTACK_CLI_ENV) is <config>/auth", () => {
+    clearTokenSources();
+    fs.writeFileSync(
+      path.join(CONFIG_ROOT, "auth"),
+      JSON.stringify({ access_token: "default-access-token" }),
+    );
+
+    expect(getAccessToken()).toBe("default-access-token");
+  });
+
+  test("PHYSTACK_CLI_AUTH_FILE_PATH overrides the env-derived auth path", () => {
+    clearTokenSources();
+    const overridePath = path.join(CONFIG_ROOT, "custom-auth.json");
+    fs.writeFileSync(
+      overridePath,
+      JSON.stringify({ access_token: "override-token" }),
+    );
+    process.env.PHYSTACK_CLI_AUTH_FILE_PATH = overridePath;
+
+    expect(getAccessToken()).toBe("override-token");
+  });
+
+  test("returns null when no source provides a token", () => {
+    clearTokenSources();
+    expect(getAccessToken()).toBeNull();
+  });
+});
+
+describe("getAccessToken — malformed JSON fall-through", () => {
+  test("malformed developer-token.json logs and falls through to the auth file", () => {
+    clearTokenSources();
+    fs.writeFileSync(DEVELOPER_TOKEN_FILE, "{ this is not json");
+    fs.writeFileSync(
+      path.join(CONFIG_ROOT, "auth"),
+      JSON.stringify({ access_token: "recovered-token" }),
+    );
+
+    expect(getAccessToken()).toBe("recovered-token");
+  });
+
+  test("malformed auth file logs and resolves to null", () => {
+    clearTokenSources();
+    fs.writeFileSync(path.join(CONFIG_ROOT, "auth"), "not-json-at-all");
+
+    expect(getAccessToken()).toBeNull();
+  });
+
+  test("developer-token.json present but missing `.token` yields undefined token", () => {
+    clearTokenSources();
+    // JSON parses fine but has no `token` field → returns data.token (undefined),
+    // which the function returns directly (faithful to the original behavior).
+    fs.writeFileSync(DEVELOPER_TOKEN_FILE, JSON.stringify({ notToken: "x" }));
+
+    expect(getAccessToken()).toBeUndefined();
+  });
+});

package/src/services/dev-token.ts

@@ -0,0 +1,52 @@
+import fs from "fs";
+import { DEVELOPER_TOKEN_FILE, getAuthFilePath } from "../utils/config-paths";
+
+/**
+ * Read-only access-token resolution, faithfully replicating
+ * `AuthService.getAccessToken()` from the legacy CLI's
+ * device-grant-auth.service (read paths only).
+ *
+ * The interactive device-grant and refresh flows (which require openid-client)
+ * are unreachable from the simulator — `start.ts` only ever reads a cached
+ * token — so they are deliberately not ported, keeping the standalone binary
+ * openid-client-free. The cached-token read paths are preserved verbatim so a
+ * user who ran `phy login` (token on disk) can still use `--connect` without
+ * setting PHYSTACK_SESSION_COOKIE / PHYSTACK_API_KEY.
+ */
+export function getAccessToken(): string | null {
+  // First check environment variable
+  const envToken = process.env.PHYSTACK_DEVELOPER_TOKEN?.trim();
+  if (envToken) {
+    return envToken;
+  }
+
+  // Then check stored developer token
+  if (fs.existsSync(DEVELOPER_TOKEN_FILE)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(DEVELOPER_TOKEN_FILE, "utf8"));
+      return data.token;
+    } catch (error) {
+      console.error(
+        `Failed to read developer token: ${error?.message ?? String(error)}`,
+      );
+    }
+  }
+
+  // Finally check device tokens. A TokenSet is just JSON on disk; read
+  // `.access_token` directly rather than reconstructing openid-client's
+  // TokenSet (which would pull the dependency back in).
+  const tokensPath =
+    process.env.PHYSTACK_CLI_AUTH_FILE_PATH ||
+    getAuthFilePath(process.env.PHYSTACK_CLI_ENV);
+  try {
+    if (fs.existsSync(tokensPath)) {
+      const tokens = JSON.parse(fs.readFileSync(tokensPath, "utf8"));
+      return tokens ? tokens.access_token : null;
+    }
+  } catch (error) {
+    console.error(
+      `Failed to read tokens at ${tokensPath}: ${error?.message ?? String(error)}`,
+    );
+  }
+  return null;
+}

package/src/services/env.ts

@@ -0,0 +1,10 @@
+const DEFAULT_API_URL = "https://api.phystack.com";
+
+export function resolveApiUrl(): string {
+  const { PHYSTACK_CLI_ENV } = process.env;
+  if (PHYSTACK_CLI_ENV) {
+    const url = process.env[`${PHYSTACK_CLI_ENV}_PHYSTACK_API`];
+    if (url) return url;
+  }
+  return process.env.PHYSTACK_API || DEFAULT_API_URL;
+}