@matter/nodejs-shell 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

package/src/MatterNode.ts

@@ -6,86 +6,75 @@
 
 // Include this first to auto-register Crypto, Network and Time Node.js implementations
 import {
-    Diagnostic,
+    Duration,
     Environment,
     Filesystem,
+    ImplementationError,
+    InternalError,
     Logger,
     ObserverGroup,
+    Seconds,
     StorageContext,
     StorageManager,
     StorageService,
 } from "@matter/general";
-import { DclBehavior, ServerNode, SoftwareUpdateManager } from "@matter/node";
-import { NodeId } from "@matter/types";
-import { CommissioningController } from "@project-chip/matter.js";
 import {
-    CommissioningControllerNodeOptions,
+    ClientNode,
+    ControllerBehavior,
+    DclBehavior,
     Endpoint,
-    NodeStateInformation,
-    PairedNode,
-} from "@project-chip/matter.js/device";
+    NetworkClient,
+    ServerNode,
+    SoftwareUpdateManager,
+} from "@matter/node";
+import { OtaProviderEndpoint } from "@matter/node/endpoints/ota-provider";
+import { Ble, Fabric, FabricAuthority } from "@matter/protocol";
+import { NodeId } from "@matter/types";
 import { join } from "node:path";
+import { installDiagnosticLogging } from "./util/diagnosticLogging.js";
+import {
+    cleanupLegacyStorage as purgeLegacyStorage,
+    eraseLegacyStorage,
+    migrateLegacyCommissionedNodes,
+    migrateLegacyControllerCredentials,
+} from "./util/legacyStorageMigration.js";
+
+const logger = Logger.get("Node");
+
+const ADMIN_FABRIC_LABEL = "matter.js Shell";
 
 /**
- * The shell's default per-node diagnostic callbacks — state-information, attribute-change and event logging. Applied by
- * default to every {@link MatterNode.connectAndGetNodes} connection so any command that reaches a node (not just
- * `nodes connect`) gets the same logging regardless of which command touched the node first.
+ * Options for {@link MatterNode.connectAndGetNodes}, expressed in the legacy vocabulary and mapped onto
+ * {@link NetworkClient} state per docs/MIGRATION_CONTROLLER_018.md.
  */
-export function createDiagnosticCallbacks(): Partial<CommissioningControllerNodeOptions> {
-    return {
-        attributeChangedCallback: (peerNodeId, { path: { nodeId, clusterId, endpointId, attributeName }, value }) =>
-            console.log(
-                `attributeChangedCallback ${peerNodeId}: Attribute ${nodeId}/${endpointId}/${clusterId}/${attributeName} changed to ${Diagnostic.json(
-                    value,
-                )}`,
-            ),
-        eventTriggeredCallback: (peerNodeId, { path: { nodeId, clusterId, endpointId, eventName }, events }) =>
-            console.log(
-                `eventTriggeredCallback ${peerNodeId}: Event ${nodeId}/${endpointId}/${clusterId}/${eventName} triggered with ${Diagnostic.json(
-                    events,
-                )}`,
-            ),
-        stateInformationCallback: (peerNodeId, info) => {
-            switch (info) {
-                case NodeStateInformation.Connected:
-                    console.log(`stateInformationCallback Node ${peerNodeId} connected`);
-                    break;
-                case NodeStateInformation.Disconnected:
-                    console.log(`stateInformationCallback Node ${peerNodeId} disconnected`);
-                    break;
-                case NodeStateInformation.Reconnecting:
-                    console.log(`stateInformationCallback Node ${peerNodeId} reconnecting`);
-                    break;
-                case NodeStateInformation.WaitingForDeviceDiscovery:
-                    console.log(
-                        `stateInformationCallback Node ${peerNodeId} waiting that device gets discovered again`,
-                    );
-                    break;
-                case NodeStateInformation.StructureChanged:
-                    console.log(`stateInformationCallback Node ${peerNodeId} structure changed`);
-                    break;
-                case NodeStateInformation.Decommissioned:
-                    console.log(`stateInformationCallback Node ${peerNodeId} decommissioned`);
-                    break;
-            }
-        },
-    };
+export interface ConnectClientNodeOptions {
+    /** When `false`, the node is not connected (left offline); it is never disabled. */
+    autoConnect?: boolean;
+    /** When `true`, opts into a subscription on connect; otherwise the node connects without subscribing. */
+    autoSubscribe?: boolean;
+    /** Maps to {@link NetworkClient.State.defaultSubscription}.minIntervalFloor. */
+    subscribeMinIntervalFloorSeconds?: number;
+    /** Maps to {@link NetworkClient.State.defaultSubscription}.maxIntervalCeiling. */
+    subscribeMaxIntervalCeilingSeconds?: number;
 }
 
-const logger = Logger.get("Node");
-
 export class MatterNode {
     #storageLocation?: string;
     #storageManager?: StorageManager;
     #storageContext?: StorageContext;
     readonly #environment: Environment;
-    commissioningController?: CommissioningController;
+    #nodeEnvironment?: Environment;
+    #node?: ServerNode;
+    #nodePromise?: Promise<ServerNode>;
+    #fabric?: Fabric;
     #started = false;
+    #startPromise?: Promise<void>;
     readonly #nodeNum: number;
     readonly #netInterface?: string;
     #dclFetchTestCertificates = false;
     #allowTestOtaImages = false;
     #transportPreference?: "tcp" | "udp";
+    #bleEnabled = false;
     #observers?: ObserverGroup;
 
     constructor(nodeNum: number, netInterface?: string) {
@@ -104,83 +93,159 @@ export class MatterNode {
     }
 
     get node(): ServerNode {
-        if (this.commissioningController === undefined) {
-            throw new Error("CommissioningController not initialized. Start first");
+        if (this.#node === undefined) {
+            throw new ImplementationError("Controller node not initialized. Call initialize() first.");
         }
-        return this.commissioningController.node;
+        return this.#node;
+    }
+
+    /**
+     * The OTA provider endpoint on the controller node. The cast is unavoidable: `endpoints.for(id)` resolves by
+     * runtime id lookup, so it cannot statically know which endpoint type lives at "ota-provider".
+     */
+    get otaProviderEndpoint(): Endpoint<OtaProviderEndpoint> {
+        return this.node.endpoints.for("ota-provider") as Endpoint<OtaProviderEndpoint>;
     }
 
     async otaService() {
+        await this.start();
         const service = await this.node.act(agent => agent.get(DclBehavior).otaUpdateService);
         await service.construction;
         return service;
     }
 
     async certificateService() {
+        await this.start();
         const service = await this.node.act(agent => agent.get(DclBehavior).certificateService);
         await service.construction;
         return service;
     }
 
     async vendorInfoService() {
+        await this.start();
         const service = await this.node.act(agent => agent.get(DclBehavior).vendorInfoService);
         await service.construction;
         return service;
     }
 
-    async initialize(resetStorage: boolean) {
-        /**
-         * Initialize the storage system.
-         *
-         * The Matter server then also uses the storage manager, so this code block in general is required,
-         * but you can choose a different storage backend as long as it implements the required API.
-         */
-
-        if (this.#environment) {
-            if (this.#netInterface !== undefined) {
-                this.#environment.vars.set("mdns.networkinterface", this.#netInterface);
-            }
+    async initialize(resetStorage: boolean, cleanupLegacyStorage = false) {
+        if (this.#netInterface !== undefined) {
+            this.#environment.vars.set("mdns.networkinterface", this.#netInterface);
+        }
 
-            const id = `shell-${this.#nodeNum.toString()}`;
+        const id = `shell-${this.#nodeNum.toString()}`;
+
+        // Scope the controller node's services (storage, mDNS) under its id, mirroring the legacy controller wrapper.
+        const nodeEnvironment = new Environment(id, this.#environment);
+        this.#nodeEnvironment = nodeEnvironment;
+
+        // Open storage up front so persisted settings are available before the controller node is built.
+        this.#storageManager = await nodeEnvironment.get(StorageService).open(id);
+        this.#storageContext = this.#storageManager.createContext("Node");
 
-            // Open storage up front so persisted settings can flow into the CommissioningController constructor.
-            this.#storageManager = await this.#environment.get(StorageService).open(id);
-            this.#storageContext = this.#storageManager.createContext("Node");
+        this.#dclFetchTestCertificates = await this.#storageContext.get<boolean>("DclFetchTestCertificates", false);
+        this.#allowTestOtaImages = await this.#storageContext.get<boolean>("AllowTestOtaImages", false);
+        const storedPref = await this.#storageContext.get<string>("TransportPreference", "");
+        this.#transportPreference = storedPref === "tcp" || storedPref === "udp" ? storedPref : undefined;
 
-            this.#dclFetchTestCertificates = await this.#storageContext.get<boolean>("DclFetchTestCertificates", false);
-            this.#allowTestOtaImages = await this.#storageContext.get<boolean>("AllowTestOtaImages", false);
-            const storedPref = await this.#storageContext.get<string>("TransportPreference", "");
-            this.#transportPreference = storedPref === "tcp" || storedPref === "udp" ? storedPref : undefined;
+        this.#bleEnabled = (nodeEnvironment.maybeGet(Ble) ?? Environment.default.maybeGet(Ble)) !== undefined;
 
-            // Build up the "Not-so-legacy" Controller
-            this.commissioningController = new CommissioningController({
-                environment: {
-                    environment: this.#environment,
-                    id,
+        // storageLocation only reads the filesystem path; it neither creates nor onlines the node and is consumed at
+        // boot (shell history), so it stays out of the lazy #ensureNode() path.
+        if (nodeEnvironment.has(Filesystem)) {
+            this.#storageLocation = join(nodeEnvironment.get(Filesystem).path, id);
+        }
+
+        // Factory reset and legacy migration are the only paths that need the node constructed before start(),
+        // hence the eager #ensureNode() here rather than the usual lazy creation.
+        if (resetStorage) {
+            await (await this.#ensureNode()).erase();
+            // erase() clears only the current-format fabric/peers. The legacy source must go too, or the next
+            // boot's migration would re-materialize the identity and key material the reset just destroyed.
+            await eraseLegacyStorage(nodeEnvironment, id);
+            return;
+        }
+
+        // Both migration steps are self-guarding no-ops when there is nothing left to migrate, so calling them
+        // unconditionally on every boot also resumes a migration that crashed after only some peers were done.
+        // Step 1 must run before the controller ServerNode is created, so construction loads the migrated fabric.
+        await migrateLegacyControllerCredentials(nodeEnvironment, id);
+
+        const node = await this.#ensureNode();
+        const { nodes, endpoints, failed } = await migrateLegacyCommissionedNodes(node);
+        if (nodes > 0) {
+            logger.info(`Legacy storage migration: ${nodes} node(s), ${endpoints} endpoint(s) migrated`);
+        }
+        if (failed > 0) {
+            logger.warn(`${failed} peer(s) failed to migrate; do not run --cleanup-legacy-storage until resolved`);
+        }
+
+        if (cleanupLegacyStorage) {
+            if (failed > 0) {
+                logger.warn(`Skipping --cleanup-legacy-storage this run: ${failed} peer(s) failed to migrate`);
+            } else {
+                await purgeLegacyStorage(nodeEnvironment, id);
+            }
+        }
+    }
+
+    /**
+     * Lazily creates the controller {@link ServerNode} on first real use. Creation runs the controller behaviors
+     * (binding the mDNS socket), which is why boot defers it until {@link start}.
+     *
+     * Concurrent callers (e.g. two websocket requests) share one creation via {@link #nodePromise}, so the node is
+     * never built twice. A failed creation clears the cached promise so a subsequent call can retry.
+     */
+    async #ensureNode(): Promise<ServerNode> {
+        if (this.#node !== undefined) {
+            return this.#node;
+        }
+        if (this.#nodePromise !== undefined) {
+            return this.#nodePromise;
+        }
+        if (this.#nodeEnvironment === undefined) {
+            throw new ImplementationError("Controller node accessed before initialize()");
+        }
+
+        this.#nodePromise = (async () => {
+            const id = `shell-${this.#nodeNum.toString()}`;
+            const node = await ServerNode.create(ServerNode.RootEndpoint.with(ControllerBehavior), {
+                environment: this.#nodeEnvironment,
+                id,
+                network: {
+                    ble: false,
+                    tcp: true,
+                    transportPreference: this.#transportPreference,
+                    // The shell connects peers strictly on demand, so opt out of the online-time bulk connect.
+                    autoStartCommissionedPeers: false,
                 },
-                autoConnect: false,
-                adminFabricLabel: "matter.js Shell",
-                enableOtaProvider: true,
-                tcp: true,
-                transportPreference: this.#transportPreference,
                 basicInformation: {
-                    productName: "matter.js Shell",
+                    productName: ADMIN_FABRIC_LABEL,
+                },
+                controller: {
+                    adminFabricLabel: ADMIN_FABRIC_LABEL,
+                    ble: this.#bleEnabled,
+                },
+                commissioning: {
+                    enabled: false, // The controller node is never commissionable itself.
+                },
+                subscriptions: {
+                    persistenceEnabled: false, // Subscription persistence is a device feature, not a controller one.
                 },
             });
 
-            const env = this.commissioningController.env;
-            if (env.has(Filesystem)) {
-                this.#storageLocation = join(env.get(Filesystem).path, id);
-            }
+            // Pulls in SoftwareUpdateManager (and thereby DclBehavior on the root node) for OTA provider support.
+            await node.add(new Endpoint(OtaProviderEndpoint, { id: "ota-provider" }));
 
-            if (resetStorage) {
-                await this.commissioningController.node.erase();
-            }
-        } else {
-            console.log(
-                "Legacy support was removed in Matter.js 0.13. Please downgrade or migrate the storage manually",
-            );
-            process.exit(1);
+            this.#node = node;
+            return node;
+        })();
+
+        try {
+            return await this.#nodePromise;
+        } catch (e) {
+            this.#nodePromise = undefined;
+            throw e;
         }
     }
 
@@ -197,8 +262,8 @@ export class MatterNode {
             await this.Store.set("AllowTestOtaImages", value);
         }
         this.#allowTestOtaImages = value ?? false;
-        if (this.#started && this.commissioningController !== undefined) {
-            await this.commissioningController.otaProvider.setStateOf(SoftwareUpdateManager, {
+        if (this.#started && this.#node !== undefined) {
+            await this.otaProviderEndpoint.setStateOf(SoftwareUpdateManager, {
                 allowTestOtaImages: this.#allowTestOtaImages,
             });
         }
@@ -206,111 +271,185 @@ export class MatterNode {
 
     get Store() {
         if (!this.#storageContext) {
-            throw new Error("Storage uninitialized");
+            throw new ImplementationError("Storage uninitialized");
         }
         return this.#storageContext;
     }
 
     async close() {
         try {
-            await this.commissioningController?.close();
+            await this.#node?.close();
         } finally {
             this.#observers?.close();
             await this.#storageManager?.close();
         }
     }
 
+    /** Concurrent callers share one in-flight run via {@link #startPromise} so the setup below executes exactly once. */
     async start() {
         if (this.#started) {
             return;
         }
-        logger.info(`matter.js shell controller started for node ${this.#nodeNum}`);
+        if (this.#startPromise !== undefined) {
+            return this.#startPromise;
+        }
+
+        this.#startPromise = (async () => {
+            logger.info(`matter.js shell controller started for node ${this.#nodeNum}`);
+
+            const node = await this.#ensureNode();
 
-        if (this.commissioningController !== undefined) {
-            await this.commissioningController.start();
+            // Reuse the existing controller fabric (matched by CA) or create one, rotating the NOC once per runtime.
+            const fabricAuthority = await node.env.load(FabricAuthority);
+            this.#fabric = await fabricAuthority.defaultFabric({ adminFabricLabel: ADMIN_FABRIC_LABEL });
 
-            await this.commissioningController.node.setStateOf(DclBehavior, {
+            await node.start();
+
+            // The shell subscribes on demand (the `subscribe` command), never persistently. Clear any autoSubscribe
+            // carried over from a prior session or pre-migration commissioning once here, so a plain connect never
+            // resumes a subscription; the connect path then leaves autoSubscribe untouched (see below).
+            for (const peer of node.peers.commissioned) {
+                if (peer.stateOf(NetworkClient).autoSubscribe) {
+                    await peer.setStateOf(NetworkClient, { autoSubscribe: false });
+                }
+            }
+
+            await node.setStateOf(DclBehavior, {
                 fetchTestCertificates: this.#dclFetchTestCertificates,
             });
 
-            await this.commissioningController.otaProvider.setStateOf(SoftwareUpdateManager, {
+            await this.otaProviderEndpoint.setStateOf(SoftwareUpdateManager, {
                 allowTestOtaImages: this.#allowTestOtaImages,
             });
 
             if (await this.Store.has("ControllerFabricLabel")) {
-                await this.commissioningController.updateFabricLabel(
-                    await this.Store.get<string>("ControllerFabricLabel", "matter.js Shell"),
-                );
+                await this.#fabric.setLabel(await this.Store.get<string>("ControllerFabricLabel", ADMIN_FABRIC_LABEL));
             }
-        } else {
-            throw new Error("No controller initialized");
-        }
 
-        this.#observers = this.#observers ?? new ObserverGroup(this.#environment.runtime);
-        const updateManagerEvents = this.commissioningController.otaProvider.eventsOf(SoftwareUpdateManager);
-        this.#observers.on(updateManagerEvents.updateAvailable, (peer, details) => {
-            logger.info(`Update available for peer`, peer, `:`, details);
-        });
-        this.#observers.on(updateManagerEvents.updateDone, peer => {
-            logger.info(`Update done for peer`, peer);
-        });
-        this.#observers.on(updateManagerEvents.updateFailed, peer => {
-            logger.info(`Update failed for peer`, peer);
-        });
-
-        this.#started = true;
+            this.#observers = this.#observers ?? new ObserverGroup(this.#environment.runtime);
+            const updateManagerEvents = this.otaProviderEndpoint.eventsOf(SoftwareUpdateManager);
+            this.#observers.on(updateManagerEvents.updateAvailable, (peer, details) => {
+                logger.info(`Update available for peer`, peer, `:`, details);
+            });
+            this.#observers.on(updateManagerEvents.updateDone, peer => {
+                logger.info(`Update done for peer`, peer);
+            });
+            this.#observers.on(updateManagerEvents.updateFailed, peer => {
+                logger.info(`Update failed for peer`, peer);
+            });
+
+            installDiagnosticLogging(node, this.#observers);
+
+            this.#started = true;
+        })();
+
+        try {
+            await this.#startPromise;
+        } finally {
+            this.#startPromise = undefined;
+        }
     }
 
-    async connectAndGetNodes(nodeIdStr?: string, connectOptions?: CommissioningControllerNodeOptions) {
+    /**
+     * Returns the {@link ClientNode}s for the commissioned peers, connecting them (unless `autoConnect: false`).
+     * Nodes connect asynchronously; use {@link awaitSeeded} before relying on the endpoint structure.
+     */
+    async connectAndGetNodes(nodeIdStr?: string, connectOptions?: ConnectClientNodeOptions): Promise<ClientNode[]> {
         await this.start();
-        const nodeId = nodeIdStr !== undefined ? NodeId(BigInt(nodeIdStr)) : undefined;
 
-        if (this.commissioningController === undefined) {
-            throw new Error("CommissioningController not initialized");
-        }
+        const commissioned = this.node.peers.commissioned;
 
-        // Default the shell's diagnostic callbacks so a node reached via any command (icd, cluster-*, subscribe, …),
-        // not just `nodes connect`, gets the same logging. A caller-supplied option still wins.
-        const options = { ...createDiagnosticCallbacks(), ...connectOptions };
+        // A specific node id must surface its own failure; the all-nodes path is best-effort (see below).
+        const singleNodeRequested = nodeIdStr !== undefined;
 
-        if (nodeId === undefined) {
-            return await this.commissioningController.connect(options);
+        let nodes: ClientNode[];
+        if (nodeIdStr !== undefined) {
+            const nodeId = NodeId(BigInt(nodeIdStr));
+            const node = commissioned.find(peer => peer.peerAddress?.nodeId === nodeId);
+            if (node === undefined) {
+                throw new ImplementationError(`Node ${nodeId} is not commissioned!`);
+            }
+            nodes = [node];
+        } else {
+            nodes = commissioned;
         }
 
-        const node = await this.commissioningController.connectNode(nodeId, {
-            ...options /*autoConnect: false*/,
-        });
-        if (!node.initialized) {
-            await node.events.initialized;
+        for (const node of nodes) {
+            try {
+                await this.#applyClientNodeNetworkOptions(node, connectOptions);
+                if (connectOptions?.autoConnect === false) {
+                    continue;
+                }
+                // A disabled peer (persisted from a prior run) rejects start(); enable() clears isDisabled and
+                // starts it. Safe because autoStartCommissionedPeers is off, so the now-enabled peer won't
+                // auto-connect on next boot.
+                if (node.stateOf(NetworkClient).isDisabled) {
+                    await node.enable();
+                } else {
+                    await node.start();
+                }
+            } catch (e) {
+                if (singleNodeRequested) {
+                    throw e;
+                }
+                // Best-effort across all commissioned peers: one unreachable peer must not abort the rest.
+                logger.warn(`Node ${node.peerAddress?.nodeId} failed to connect:`, e);
+            }
         }
-        return [node];
+
+        return nodes;
     }
 
-    get controller() {
-        if (this.commissioningController === undefined) {
-            throw new Error("CommissioningController not initialized. Start first");
+    async #applyClientNodeNetworkOptions(node: ClientNode, options?: ConnectClientNodeOptions) {
+        // connect ≠ subscribe: a plain connect leaves autoSubscribe untouched (it was normalized to false once at
+        // startup), so a subscription established this session via the `subscribe` command survives subsequent
+        // commands.  Only an explicit opt-in flips it here.
+        if (options?.autoSubscribe !== undefined) {
+            await node.setStateOf(NetworkClient, { autoSubscribe: options.autoSubscribe });
+        }
+
+        const { subscribeMinIntervalFloorSeconds, subscribeMaxIntervalCeilingSeconds } = options ?? {};
+        if (subscribeMinIntervalFloorSeconds !== undefined || subscribeMaxIntervalCeilingSeconds !== undefined) {
+            const defaultSubscription: { minIntervalFloor?: Duration; maxIntervalCeiling?: Duration } = {};
+            if (subscribeMinIntervalFloorSeconds !== undefined) {
+                defaultSubscription.minIntervalFloor = Seconds(subscribeMinIntervalFloorSeconds);
+            }
+            if (subscribeMaxIntervalCeilingSeconds !== undefined) {
+                defaultSubscription.maxIntervalCeiling = Seconds(subscribeMaxIntervalCeilingSeconds);
+            }
+            await node.setStateOf(NetworkClient, { defaultSubscription });
         }
-        return this.commissioningController;
     }
 
+    /**
+     * Iterates the endpoints of each {@link ClientNode}, including the root endpoint (number 0); pass
+     * {@link endpointIds} to restrict iteration.
+     */
     async iterateNodeDevices(
-        nodes: PairedNode[],
-        callback: (device: Endpoint, node: PairedNode) => Promise<void>,
-        endpointId?: number,
-    ) {
+        nodes: ClientNode[],
+        callback: (device: Endpoint, node: ClientNode) => Promise<void>,
+        endpointIds?: number[],
+    ): Promise<void> {
         for (const node of nodes) {
-            let devices = node.getDevices();
-            if (endpointId !== undefined) {
-                devices = devices.filter(device => device.number === endpointId);
-            }
-
-            for (const device of devices) {
+            for (const device of node.endpoints) {
+                if (endpointIds !== undefined && !endpointIds.includes(device.number)) {
+                    continue;
+                }
                 await callback(device, node);
             }
         }
     }
 
-    updateFabricLabel(label: string) {
-        return this.commissioningController?.updateFabricLabel(label);
+    /**
+     * Updates the controller's admin fabric label on the local fabric. Propagation to already-connected peers is not
+     * reproduced and moves to the node-management layer per docs/MIGRATION_CONTROLLER_018.md.
+     * MIGRATION-GAP: updatefabriclabel-note.
+     */
+    async updateFabricLabel(label: string) {
+        await this.start();
+        if (this.#fabric === undefined) {
+            throw new InternalError("Controller fabric not initialized");
+        }
+        await this.#fabric.setLabel(label);
     }
 }

package/src/app.ts

@@ -81,6 +81,12 @@ async function main() {
                             default: false,
                             type: "boolean",
                         },
+                        "cleanup-legacy-storage": {
+                            description:
+                                "Irreversibly delete pre-0.16 storage artifacts after migration. Only use this once you are certain the migration succeeded and you will not downgrade below 0.16.",
+                            default: false,
+                            type: "boolean",
+                        },
                         netInterface: {
                             description: "Network interface to use for MDNS announcements and scanning.",
                             type: "string",
@@ -126,6 +132,7 @@ async function main() {
                     bleHciId,
                     nodeType,
                     factoryReset,
+                    cleanupLegacyStorage,
                     netInterface,
                     logfile,
                     webSocketInterface,
@@ -134,8 +141,17 @@ async function main() {
                     webAddress,
                 } = argv;
 
+                // Install BLE before the controller node initializes: the Ble service is registered reactively
+                // when `ble.enable` flips, and the node reads its availability during initialize().
+                if (bleEnable) {
+                    Environment.default.vars.set("ble.enable", true);
+                }
+                if (bleHciId !== undefined) {
+                    Environment.default.vars.set("ble.hci.id", bleHciId);
+                }
+
                 theNode = new MatterNode(nodeNum, netInterface);
-                await theNode.initialize(factoryReset);
+                await theNode.initialize(factoryReset, cleanupLegacyStorage);
 
                 if (logfile !== undefined) {
                     await theNode.Store.set("LogFile", logfile);
@@ -159,14 +175,6 @@ async function main() {
                     theShell = new Shell(theNode, nodeNum, PROMPT, process.stdin, process.stdout);
                 }
 
-                if (bleEnable) {
-                    Environment.default.vars.set("ble.enable", true);
-                }
-
-                if (bleHciId !== undefined) {
-                    Environment.default.vars.set("ble.hci.id", bleHciId);
-                }
-
                 console.log(`Started Node #${nodeNum} (Type: ${nodeType}) ${bleEnable ? "with" : "without"} BLE`);
                 if (!webSocketInterface) {
                     theShell.start(theNode.storageLocation);