@phystack/device-simulator 6.3.0

package/src/utils/__tests__/simulator-config.test.ts

@@ -0,0 +1,230 @@
+import { 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";
+
+// os.homedir() is redirected to SUITE_TEST_HOME by the test preload (wired via
+// bunfig.toml) BEFORE any module — including config-paths.ts, which computes
+// CONFIG_DIR = os.homedir()/.config/phystack-cli at import time — is evaluated.
+// On macOS/Linux os.homedir() reads the OS user database and ignores
+// process.env.HOME, so the preload override (not a mere HOME assignment) is what
+// keeps the real ~/.config/phystack-cli untouched. We reuse the same root here
+// so the on-disk-path assertions below match what the module under test uses.
+const TEST_HOME = SUITE_TEST_HOME;
+const CONFIG_ROOT = path.join(TEST_HOME, ".config", "phystack-cli");
+
+const configModule = await import("../simulator-config");
+const {
+  saveDeviceConfig,
+  getDeviceConfig,
+  saveAppConfig,
+  getAppConfig,
+  getAppConfigByPath,
+  listApps,
+  updateAppTwinId,
+  saveSimulator,
+  getSimulator,
+  listSimulators,
+  removeSimulator,
+} = configModule;
+
+describe("simulator-config — persistence isolation", () => {
+  test("config root resolves under the temp HOME, not the real home", () => {
+    expect(CONFIG_ROOT.startsWith(TEST_HOME)).toBe(true);
+    // The user's real home must NOT be the test root (proves isolation).
+    expect(TEST_HOME).not.toBe(os.userInfo().homedir);
+  });
+});
+
+describe("simulator-config — device config round-trip", () => {
+  test("saveDeviceConfig writes JSON under simulator/tenants/<id> and reads back identical", async () => {
+    const tenantId = "tenant-device-rt";
+    const config = {
+      deviceId: "dev-123",
+      tenantId: "tenant-obj-id",
+      deviceTwinId: "twin-456",
+    };
+    await saveDeviceConfig(tenantId, config);
+
+    const onDisk = path.join(
+      CONFIG_ROOT,
+      "simulator",
+      "tenants",
+      tenantId,
+      "device.json",
+    );
+    expect(fs.existsSync(onDisk)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(onDisk, "utf8"))).toEqual(config);
+    // Exact serialization shape: 2-space indented JSON.
+    expect(fs.readFileSync(onDisk, "utf8")).toBe(
+      JSON.stringify(config, null, 2),
+    );
+
+    expect(await getDeviceConfig(tenantId)).toEqual(config);
+  });
+
+  test("getDeviceConfig returns undefined when none saved", async () => {
+    expect(await getDeviceConfig("tenant-never-saved")).toBeUndefined();
+  });
+});
+
+describe("simulator-config — app config round-trip", () => {
+  test("saveAppConfig stores by app name and reads back via getAppConfig", async () => {
+    const tenantId = "tenant-app-rt";
+    const appConfig = {
+      name: "my-app",
+      type: "screen" as any,
+      path: "/abs/path/to/my-app",
+      twinId: "twin-app-1",
+      devCommand: "npm run dev",
+    };
+    await saveAppConfig(tenantId, appConfig);
+
+    const onDisk = path.join(
+      CONFIG_ROOT,
+      "simulator",
+      "tenants",
+      tenantId,
+      "my-app.json",
+    );
+    expect(fs.existsSync(onDisk)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(onDisk, "utf8"))).toEqual(appConfig);
+
+    expect(await getAppConfig(tenantId, "my-app")).toEqual(appConfig);
+  });
+
+  test("getAppConfigByPath resolves the app whose `path` matches", async () => {
+    const tenantId = "tenant-app-bypath";
+    const first = {
+      name: "app-one",
+      type: "edge" as any,
+      path: "/abs/one",
+      devCommand: "docker",
+    };
+    const second = {
+      name: "app-two",
+      type: "screen" as any,
+      path: "/abs/two",
+      devCommand: "npm start",
+    };
+    await saveAppConfig(tenantId, first);
+    await saveAppConfig(tenantId, second);
+
+    expect(await getAppConfigByPath(tenantId, "/abs/two")).toEqual(second);
+    expect(await getAppConfigByPath(tenantId, "/abs/missing")).toBeUndefined();
+  });
+
+  test("listApps returns every saved app config for the tenant", async () => {
+    const tenantId = "tenant-list-apps";
+    const appA = {
+      name: "a",
+      type: "screen" as any,
+      path: "/a",
+      devCommand: "npm start",
+    };
+    const appB = {
+      name: "b",
+      type: "edge" as any,
+      path: "/b",
+      devCommand: "docker",
+    };
+    await saveAppConfig(tenantId, appA);
+    await saveAppConfig(tenantId, appB);
+
+    const apps = await listApps(tenantId);
+    expect(apps.map((app) => app.name).sort()).toEqual(["a", "b"]);
+  });
+
+  test("listApps returns empty array for an unknown tenant", async () => {
+    expect(await listApps("tenant-no-apps")).toEqual([]);
+  });
+
+  test("updateAppTwinId rewrites only the twinId, preserving other fields", async () => {
+    const tenantId = "tenant-update-twin";
+    const appConfig = {
+      name: "updatable",
+      type: "screen" as any,
+      path: "/updatable",
+      twinId: "old-twin",
+      devCommand: "npm run dev",
+    };
+    await saveAppConfig(tenantId, appConfig);
+
+    await updateAppTwinId(tenantId, "updatable", "new-twin");
+
+    const reread = await getAppConfig(tenantId, "updatable");
+    expect(reread).toEqual({ ...appConfig, twinId: "new-twin" });
+  });
+});
+
+describe("simulator-config — simulator (provisioned device) store", () => {
+  test("saveSimulator writes simulators/<name>.json in 2-space JSON and round-trips", () => {
+    const config = {
+      name: "sim-roundtrip",
+      deviceId: "device-abc",
+      accessKey: "secret-key",
+      serialNumber: "SIM-0001",
+      environment: "prod",
+      provisionedAt: "2026-06-16T00:00:00.000Z",
+      tenantId: "tenant-1",
+    };
+    saveSimulator(config);
+
+    const onDisk = path.join(CONFIG_ROOT, "simulators", "sim-roundtrip.json");
+    expect(fs.existsSync(onDisk)).toBe(true);
+    expect(fs.readFileSync(onDisk, "utf8")).toBe(
+      JSON.stringify(config, null, 2),
+    );
+
+    expect(getSimulator("sim-roundtrip")).toEqual(config);
+  });
+
+  test("getSimulator returns null for an unknown name", () => {
+    expect(getSimulator("does-not-exist")).toBeNull();
+  });
+
+  test("listSimulators returns all saved configs; empty when dir absent", () => {
+    // Fresh isolated names so this assertion does not depend on other tests.
+    const alpha = {
+      name: "list-alpha",
+      deviceId: "dev-a",
+      accessKey: "k-a",
+      serialNumber: "SIM-A",
+      environment: "dev",
+      provisionedAt: "2026-06-16T00:00:00.000Z",
+    };
+    const beta = {
+      name: "list-beta",
+      deviceId: "dev-b",
+      accessKey: "k-b",
+      serialNumber: "SIM-B",
+      environment: "qa",
+      provisionedAt: "2026-06-16T00:00:00.000Z",
+    };
+    saveSimulator(alpha);
+    saveSimulator(beta);
+
+    const names = listSimulators().map((sim) => sim.name);
+    expect(names).toContain("list-alpha");
+    expect(names).toContain("list-beta");
+  });
+
+  test("removeSimulator deletes the file and returns true; false when absent", () => {
+    const config = {
+      name: "sim-to-remove",
+      deviceId: "dev-x",
+      accessKey: "k-x",
+      serialNumber: "SIM-X",
+      environment: "prod",
+      provisionedAt: "2026-06-16T00:00:00.000Z",
+    };
+    saveSimulator(config);
+    const onDisk = path.join(CONFIG_ROOT, "simulators", "sim-to-remove.json");
+    expect(fs.existsSync(onDisk)).toBe(true);
+
+    expect(removeSimulator("sim-to-remove")).toBe(true);
+    expect(fs.existsSync(onDisk)).toBe(false);
+    expect(removeSimulator("sim-to-remove")).toBe(false);
+  });
+});

package/src/utils/config-paths.ts

@@ -0,0 +1,38 @@
+import path from "path";
+import os from "os";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".config", "phystack-cli");
+
+export const TENANT_FILE = path.join(CONFIG_DIR, "tenant.json");
+export const CREDENTIALS_FILE = path.join(
+  CONFIG_DIR,
+  "registry-credentials.json",
+);
+export const VALIDATION_CACHE_FILE = path.join(
+  CONFIG_DIR,
+  "credential-validation-cache.json",
+);
+export const EMULATED_DEVICE_FILE = path.join(CONFIG_DIR, "device.json");
+export const DEVELOPER_TOKEN_FILE = path.join(
+  CONFIG_DIR,
+  "developer-token.json",
+);
+
+export const SIMULATORS_DIR = path.join(CONFIG_DIR, "simulators");
+export const SIMULATOR_DIR = path.join(CONFIG_DIR, "simulator");
+export const VMS_DIR = path.join(CONFIG_DIR, "vms");
+export const CACHE_DIR = path.join(CONFIG_DIR, "cache");
+
+export function getAuthFilePath(gridEnv = ""): string {
+  const formatted = gridEnv.toUpperCase();
+  switch (formatted) {
+    case "LOCAL":
+      return path.join(CONFIG_DIR, "auth-local");
+    case "DEV":
+      return path.join(CONFIG_DIR, "auth-dev");
+    case "QA":
+      return path.join(CONFIG_DIR, "auth-qa");
+    default:
+      return path.join(CONFIG_DIR, "auth");
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,41 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import chalk from "chalk";
+import path from "path";
+import fs from "fs";
+
+// Injected at compile time by `bun build --define`. In a compiled binary
+// __dirname points at the embedded VFS root, so reading ../../package.json
+// fails; in dev (tsc/bun --watch) the define is absent and we fall back to
+// reading the sibling package.json off disk.
+declare const __PKG_VERSION__: string | undefined;
+
+function resolvePackageVersion(): string {
+  if (typeof __PKG_VERSION__ !== "undefined") {
+    return __PKG_VERSION__;
+  }
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"),
+    );
+    return pkg.version || "0.0.0";
+  } catch (e) {
+    console.error(chalk.dim("Cannot read package version"));
+    return "0.0.0";
+  }
+}
+
+const packageVersion = resolvePackageVersion();
+
+export const getPackageVersion = () => packageVersion;
+
+export const handleError =
+  <T = any>(cb) =>
+  async (...args) => {
+    try {
+      const result = (await cb(...args)) as any as T;
+      return result;
+    } catch (e) {
+      console.error(chalk.red(e.toString()));
+      return process.exit(1);
+    }
+  };

package/src/utils/simulator-config.ts

@@ -0,0 +1,185 @@
+import fs from "fs-extra";
+import path from "path";
+import { AppConfig, DeviceConfig } from "../simulator/types";
+import { SIMULATORS_DIR, SIMULATOR_DIR } from "./config-paths";
+
+export interface SimulatorConnectConfig {
+  name: string;
+  deviceId: string;
+  accessKey: string;
+  serialNumber: string;
+  // Optional: when unset, the connect path lets @phystack/hub-device synthesize
+  // the URL from `dataResidency` (LOCAL maps to localhost:14401, real regions
+  // follow the public template). Only set when overriding via
+  // PHYSTACK_SIMULATOR_PHYHUB_URL or when a previous provisioning baked it in
+  // (back-compat with pre-fix saved configs).
+  phyhubUrl?: string;
+  // The CLI's deployment env (from PHYSTACK_CLI_ENV, lowercased). Drives the
+  // POST body's `env` field at provisioning time. NOT the same as residency.
+  environment: string;
+  // Tenant's data residency (LOCAL/DEV/QA/EU/US/AU/IN/UAE) — passed as
+  // `region` to hub-device at connect time so it can synthesize the correct
+  // phyhub Socket.IO URL. Resolved at provisioning time from the active
+  // tenant (`phy tenant select`) or derived from `environment` as a fallback.
+  // Optional for back-compat with pre-fix saved configs.
+  dataResidency?: string;
+  provisionedAt: string;
+  tenantId?: string;
+  spaceId?: string;
+}
+
+export function listSimulators(): SimulatorConnectConfig[] {
+  if (!fs.pathExistsSync(SIMULATORS_DIR)) return [];
+  return fs
+    .readdirSync(SIMULATORS_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        return JSON.parse(
+          fs.readFileSync(path.join(SIMULATORS_DIR, f), "utf8"),
+        );
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean) as SimulatorConnectConfig[];
+}
+
+export function getSimulator(name: string): SimulatorConnectConfig | null {
+  const filePath = path.join(SIMULATORS_DIR, `${name}.json`);
+  if (!fs.pathExistsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function saveSimulator(config: SimulatorConnectConfig): void {
+  fs.ensureDirSync(SIMULATORS_DIR);
+  fs.writeFileSync(
+    path.join(SIMULATORS_DIR, `${config.name}.json`),
+    JSON.stringify(config, null, 2),
+  );
+}
+
+export function removeSimulator(name: string): boolean {
+  const filePath = path.join(SIMULATORS_DIR, `${name}.json`);
+  if (!fs.pathExistsSync(filePath)) return false;
+  fs.removeSync(filePath);
+  return true;
+}
+
+function deviceConfigPath(tenantId: string): string {
+  return path.join(tenantDir(tenantId), "device.json");
+}
+
+export async function getDeviceConfig(
+  tenantId: string,
+): Promise<DeviceConfig | undefined> {
+  const filePath = deviceConfigPath(tenantId);
+  try {
+    if (await fs.pathExists(filePath)) {
+      const data = await fs.readFile(filePath, "utf8");
+      return JSON.parse(data) as DeviceConfig;
+    }
+    return undefined;
+  } catch (err) {
+    console.log(`[simulator] Failed to read device config: ${err.message}`);
+    return undefined;
+  }
+}
+
+export async function saveDeviceConfig(
+  tenantId: string,
+  config: DeviceConfig,
+): Promise<void> {
+  const dir = tenantDir(tenantId);
+  await fs.ensureDir(dir);
+  await fs.writeFile(
+    deviceConfigPath(tenantId),
+    JSON.stringify(config, null, 2),
+  );
+}
+
+function tenantsDir(): string {
+  return path.join(SIMULATOR_DIR, "tenants");
+}
+
+function tenantDir(tenantId: string): string {
+  return path.join(tenantsDir(), tenantId);
+}
+
+function appConfigPath(tenantId: string, appName: string): string {
+  return path.join(tenantDir(tenantId), `${appName}.json`);
+}
+
+export async function getAppConfig(
+  tenantId: string,
+  appName: string,
+): Promise<AppConfig | undefined> {
+  const filePath = appConfigPath(tenantId, appName);
+  try {
+    if (await fs.pathExists(filePath)) {
+      const data = await fs.readFile(filePath, "utf8");
+      return JSON.parse(data) as AppConfig;
+    }
+    return undefined;
+  } catch (err) {
+    console.log(
+      `[simulator] Failed to read app config for ${appName}: ${err.message}`,
+    );
+    return undefined;
+  }
+}
+
+export async function saveAppConfig(
+  tenantId: string,
+  config: AppConfig,
+): Promise<void> {
+  const dir = tenantDir(tenantId);
+  await fs.ensureDir(dir);
+  const filePath = appConfigPath(tenantId, config.name);
+  await fs.writeFile(filePath, JSON.stringify(config, null, 2));
+}
+
+export async function listApps(tenantId: string): Promise<AppConfig[]> {
+  const dir = tenantDir(tenantId);
+  try {
+    if (!(await fs.pathExists(dir))) return [];
+    const files = await fs.readdir(dir);
+    const apps: AppConfig[] = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        const data = await fs.readFile(path.join(dir, file), "utf8");
+        apps.push(JSON.parse(data) as AppConfig);
+      }
+    }
+    return apps;
+  } catch (err) {
+    console.log(
+      `[simulator] Failed to list apps for tenant ${tenantId}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+export async function getAppConfigByPath(
+  tenantId: string,
+  appPath: string,
+): Promise<AppConfig | undefined> {
+  const apps = await listApps(tenantId);
+  return apps.find((a) => a.path === appPath);
+}
+
+export async function updateAppTwinId(
+  tenantId: string,
+  appName: string,
+  newTwinId: string,
+): Promise<void> {
+  const config = await getAppConfig(tenantId, appName);
+  if (config) {
+    config.twinId = newTwinId;
+    await saveAppConfig(tenantId, config);
+  }
+}

package/src/utils/tenant-storage.ts

@@ -0,0 +1,106 @@
+import fs from "fs-extra";
+import chalk from "chalk";
+import { CONFIG_DIR, TENANT_FILE } from "./config-paths";
+
+export interface StoredTenant {
+  id: string;
+  slug: string;
+  displayName: string;
+  phyhubUrl: string;
+  // Tenant's data residency (LOCAL/DEV/QA/EU/US/AU/IN/UAE) — drives the
+  // simulator's phyhub region. Optional for back-compat with pre-fix saved
+  // configs (will be re-populated on next `phy tenant select` / `phy login`).
+  dataResidency?: string;
+}
+
+/**
+ * Save tenant information to the config directory
+ *
+ * @param tenant The tenant information to save
+ * @returns Promise that resolves when the save is complete
+ */
+export const saveTenant = async (tenant: StoredTenant): Promise<void> => {
+  try {
+    // Ensure config directory exists
+    await fs.ensureDir(CONFIG_DIR);
+
+    // Save the tenant information
+    await fs.writeFile(TENANT_FILE, JSON.stringify(tenant, null, 2));
+    console.log(chalk.dim(`Saved tenant information to ${TENANT_FILE}`));
+  } catch (error) {
+    console.error(
+      chalk.red(`Failed to save tenant information: ${error.message}`),
+    );
+    throw error;
+  }
+};
+
+/**
+ * Get the saved tenant information.
+ *
+ * Pass `silent: true` to skip the "Using tenant: …" log — useful when the
+ * caller is going to print its own message about the tenant (e.g. the
+ * `phy tenant select` flow).
+ *
+ * @returns Promise that resolves to the tenant information or null if none saved
+ */
+export const getTenant = async (
+  options: { silent?: boolean } = {},
+): Promise<StoredTenant | null> => {
+  try {
+    if (await fs.pathExists(TENANT_FILE)) {
+      const data = await fs.readFile(TENANT_FILE, "utf8");
+      const tenant = JSON.parse(data) as StoredTenant;
+
+      if (!options.silent) {
+        console.log(
+          chalk.dim(`Using tenant: ${tenant.displayName} (${tenant.slug})`),
+        );
+      }
+
+      return tenant;
+    }
+    return null;
+  } catch (error) {
+    console.error(
+      chalk.red(`Failed to read tenant information: ${error.message}`),
+    );
+    return null;
+  }
+};
+
+/**
+ * Check if a tenant is already saved
+ *
+ * @returns Promise that resolves to true if a tenant is saved, false otherwise
+ */
+export const hasTenant = async (): Promise<boolean> => {
+  try {
+    return await fs.pathExists(TENANT_FILE);
+  } catch (error) {
+    console.error(
+      chalk.red(`Failed to check for saved tenant: ${error.message}`),
+    );
+    return false;
+  }
+};
+
+/**
+ * Clear the saved tenant.
+ *
+ * @returns Promise resolving to true if a tenant file was removed, false if
+ *   there was nothing to clear.
+ */
+export const clearTenant = async (): Promise<boolean> => {
+  try {
+    if (await fs.pathExists(TENANT_FILE)) {
+      await fs.remove(TENANT_FILE);
+      console.log(chalk.dim(`Removed tenant information`));
+      return true;
+    }
+    return false;
+  } catch (error) {
+    console.error(chalk.red(`Failed to clear tenant: ${error.message}`));
+    throw error;
+  }
+};

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "@phystack/tsconfig/library",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "./src",
+    "lib": ["esnext", "dom"],
+    "isolatedModules": false,
+    "strict": false
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/__tests__/**", "src/**/*.test.ts"]
+}