@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/lib/launchd-repair.js

@@ -0,0 +1,199 @@
+/**
+ * launchd-repair.ts — the `doctor --fix` launchd repair (flair#1573 slice b).
+ *
+ * Slice (a) made the no-inline-secret plist a product capability (pass-file
+ * mode + the product launcher). This module is the DECISION half of the repair
+ * that uses it: given the current launchd observation and the on-disk plist,
+ * decide what `doctor --fix` may do — and, just as importantly, what it must
+ * refuse to do. The EXECUTION half (regenerate the plist, adopt a running
+ * process, load, verify) lives in src/cli.ts, which owns the real filesystem
+ * and launchctl; everything here is pure and unit-testable without either.
+ *
+ * The two load-bearing decisions, both from the adjudication (issue comment
+ * 5607172125):
+ *
+ *   1. CONFIG AUTHORITY (flair#914). The whole fix is gated on the instance's
+ *      own harper-config.yaml being readable. ROOTPATH and the ports come from
+ *      that file — never ~/.flair/config.yaml, never defaults — because a
+ *      wrong ROOTPATH boots Harper against the wrong data directory, which is
+ *      the data-adjacent disaster this issue exists to prevent. If the config
+ *      cannot be read, there is no safe way to regenerate the plist, so the
+ *      repair refuses rather than invent a ROOTPATH.
+ *
+ *   2. OWNERSHIP GUARD (mirror flair#966). A plist is only repaired when it is
+ *      provably ours (ROOTPATH == dataDir), provably corrupt (not XML), or
+ *      absent. A valid plist whose ROOTPATH names a DIFFERENT directory is a
+ *      different instance and is refused. A valid plist with NO ROOTPATH at all
+ *      cannot be attributed, so it is refused and the file is named — the
+ *      operator decides. (No TTY confirm-adopt escape hatch exists; a
+ *      confirm-adopt for the unattributable case is slice b3, if ever.)
+ *
+ * The state matrix the plan collapses to:
+ *
+ *   - not-applicable (not macOS)  -> no-op.
+ *   - managed                     -> no-op ("already managed").
+ *   - absent / corrupt / ours     -> regenerate (pass-file mode).
+ *   - foreign / unattributable    -> refuse.
+ *   - config unreadable           -> refuse.
+ *   - detached-and-running (ours) -> adopt (clean-stop -> regenerate -> load).
+ *   - detached-and-running (foreign) -> refuse (ownership guard).
+ */
+import { resolve } from "node:path";
+/**
+ * Classify the plist at `plistPath` against `dataDir`.
+ *
+ * The "corrupt" test is deliberately structural, not a full plist parse: a
+ * Flair plist is an XML document with a `<plist>` root and a `<dict>` body,
+ * and the reported corruption (a bare JSON array) has neither. A full parser
+ * would pull the whole EnvironmentVariables dict — including the admin
+ * password — into memory to answer a question about two tags, and the shape
+ * here is fixed because buildLaunchdPlist wrote it.
+ */
+export function classifyPlist(plistPath, dataDir, deps) {
+    if (!deps.exists(plistPath))
+        return "absent";
+    const raw = deps.read(plistPath);
+    if (raw === null)
+        return "corrupt";
+    if (!/<plist[\s>]/.test(raw) || !/<dict>/.test(raw))
+        return "corrupt";
+    const rootPath = deps.readRootPath(plistPath);
+    if (rootPath === null)
+        return "unattributable";
+    return resolve(rootPath) === resolve(dataDir) ? "ours" : "foreign";
+}
+/**
+ * Decide what `doctor --fix` may do about launchd management.
+ *
+ * Pure: no filesystem, no launchctl. The executor in cli.ts turns a
+ * `regenerate` plan into a plist write + load + verify, an `adopt` plan into
+ * a clean-stop + regenerate + load + verify, and a `refuse` plan into a named
+ * refusal.
+ */
+export function planLaunchdRepair(input) {
+    const { observation, disposition, plistPath, directProcessRunning, configReadable } = input;
+    if (observation.state === "not-applicable") {
+        return { kind: "no-op", reason: "not-applicable", detail: observation.detail };
+    }
+    if (observation.state === "managed") {
+        return { kind: "no-op", reason: "already-managed", detail: observation.detail };
+    }
+    // Config authority (flair#914): no readable harper-config.yaml means no safe
+    // ROOTPATH/ports, so the repair cannot proceed without inventing them.
+    if (!configReadable) {
+        return {
+            kind: "refuse",
+            reason: "config-unreadable",
+            detail: "cannot repair launchd management: the instance's harper-config.yaml is missing or unreadable, " +
+                "so its ROOTPATH and ports cannot be established. Run 'flair init' to (re)create the instance.",
+        };
+    }
+    // Ownership guard (flair#966 mirror).
+    if (disposition === "foreign") {
+        return {
+            kind: "refuse",
+            reason: "foreign",
+            detail: `refusing to repair the launchd plist at ${plistPath}: it is registered to a different data ` +
+                "directory, so it belongs to a different Flair instance.",
+            plistPath,
+        };
+    }
+    if (disposition === "unattributable") {
+        return {
+            kind: "refuse",
+            reason: "unattributable",
+            detail: `refusing to repair the launchd plist at ${plistPath}: it has no ROOTPATH, so it cannot be ` +
+                "proven to belong to this instance.",
+            plistPath,
+        };
+    }
+    // Detached-and-running (flair#1573 slice b2): a direct (non-launchd) process
+    // is serving this instance. The plist is ours/absent/corrupt (the foreign and
+    // unattributable cases were refused above), so the direct process is THIS
+    // instance's and the adopt path clean-stops it before regenerating + loading.
+    // The plan states the bounce explicitly: adopt is the one repair that takes
+    // the live instance down and back up.
+    if (directProcessRunning) {
+        return {
+            kind: "adopt",
+            detail: "the instance is running but not under launchd (direct-spawned) — adopting it into launchd " +
+                "will clean-stop the live process (SIGTERM, wait for exit), regenerate the plist, and reload it. " +
+                "This bounces the live instance.",
+        };
+    }
+    // Repairable: absent, corrupt, or ours, with no direct process in the way.
+    return {
+        kind: "regenerate",
+        detail: "regenerating the launchd plist for this instance",
+    };
+}
+// ─── the executor's pure helpers (slice b2) ───────────────────────────────
+/**
+ * Map a throw from the executor arm to a named result (flair#1573 slice b2,
+ * Kern's b1 defect). `doctor --fix` must never crash mid-report: every throw
+ * becomes a `failed` result, except an engine-backwards refusal (flair#1093),
+ * which is a refusal by nature and is surfaced as `refused` so the operator
+ * sees the actor/state/remedy rather than a generic failure.
+ *
+ * NOTE: the engine-backwards `refused` intentionally carries its remedy in the
+ * detail prose (the actor/state/remedy sentence buildRecoveryLines renders),
+ * NOT in a structured `remedy` field — a refusal is a verdict, not a failure,
+ * and the prose is what the operator reads.
+ */
+export function mapRepairThrow(err) {
+    const e = err;
+    if (e?.engineBackwards) {
+        return { kind: "refused", reason: "engine-backwards", detail: e.message ?? "engine is backwards" };
+    }
+    return {
+        kind: "failed",
+        detail: e?.message ?? String(err),
+        remedy: ["flair doctor --fix"],
+    };
+}
+/**
+ * Decide whether the adopt path may proceed to regenerate + load, given the
+ * liveness classification of the direct process and the post-stop health probe
+ * (flair#1573 slice b2). Pure — the SIGTERM + wait and the probe happen in the
+ * executor; this only maps their results to a verdict.
+ *
+ *   - DISAGREEMENT / UNKNOWN -> failed (never stop a foreign/unattributable
+ *     process — the liveness machine refused to verify identity).
+ *   - post-stop health "ok"  -> failed ("port still occupied" — the old
+ *     process did not fully exit, so loading the new plist would collide).
+ *   - post-stop health "unreachable" -> failed ("port not confirmed free" — a
+ *     wedged daemon that ignored SIGTERM but stays BOUND to the port while no
+ *     longer serving /Health would EADDRINUSE on load; "unreachable" is the
+ *     probe's "cannot tell", so it must NOT proceed).
+ *   - post-stop health "refused" -> proceed (ECONNREFUSED — nothing is
+ *     listening, the port is provably free).
+ */
+export function decideAdoptStop(state, postStopHealth) {
+    switch (state.state) {
+        case "RUNNING":
+        case "WEDGED":
+        case "NOT_RUNNING":
+            break;
+        case "DISAGREEMENT":
+        case "UNKNOWN":
+            return {
+                kind: "failed",
+                detail: `refusing to adopt: ${state.detail}`,
+                remedy: ["flair stop", "flair doctor --fix"],
+            };
+    }
+    // Proceed ONLY when the port is provably free (ECONNREFUSED). "ok" or
+    // "foreign" means something is still serving; "unreachable" means a wedged
+    // daemon may still be BOUND to the port (ignored SIGTERM) — both would
+    // EADDRINUSE on load.
+    if (postStopHealth.kind !== "refused") {
+        return {
+            kind: "failed",
+            detail: postStopHealth.kind === "ok" || postStopHealth.kind === "foreign"
+                ? "port still occupied after stopping the direct process"
+                : "port not confirmed free after stopping the direct process (a wedged process may still hold it)",
+            remedy: ["flair stop", "flair doctor --fix"],
+        };
+    }
+    return "proceed";
+}

package/dist/lib/ops-api-bind.js

@@ -0,0 +1,115 @@
+/**
+ * ops-api-bind.ts — one decision for "is the Harper ops API bound to all
+ * interfaces?", shared by `flair doctor` and `flair status` (flair#670,
+ * unified in flair#852).
+ *
+ * The Harper ops API used to bind all interfaces unconditionally. `flair init`
+ * now defaults it to loopback + the domain socket, with an escape hatch
+ * (`--ops-bind` / `FLAIR_OPS_BIND`) for deployments that genuinely need remote
+ * ops access (flair#670). That narrowing is only useful if every health surface
+ * agrees on what the running install actually bound, and it is what doctor
+ * reads out of Harper's own config. The predicate is an allow-list: ONLY a
+ * loopback host narrows the bind. A bare numeric port, a wildcard host
+ * (`0.0.0.0:19925`, `[::]:19925`, …), an empty/unspecified host and an
+ * unparseable value are all reported as exposed — a `host:port` string is not
+ * evidence of narrowing unless the host is actually loopback.
+ *
+ * That allow-list is the flair#852 wildcard blind spot. The detector originally
+ * treated ANY `host:port` as narrowed, so `flair init --ops-bind 0.0.0.0`
+ * persisted `0.0.0.0:19925` and both `flair status` and `flair doctor` printed
+ * green while the ops API was reachable off-box.
+ *
+ * flair#852 was the two surfaces disagreeing. `flair doctor` flagged the bare
+ * port while `flair status` printed "✓ all checks passing" — a security-relevant
+ * exposure visible to one command and invisible to the other, so users shipped
+ * with the ops API reachable off-box. The fix is structural: the decision lives
+ * HERE, both commands call it, and status folds the finding into the same
+ * warning verdict that drives its green line.
+ *
+ * Pure: parsing Harper's config is the caller's job (doctor/status both read it
+ * with `readHarperConfig`); this module only decides.
+ */
+/**
+ * Hosts that genuinely narrow the ops-API bind to loopback. This is an
+ * allow-list on purpose: ANYTHING not in it — a wildcard (`0.0.0.0`, `::`,
+ * `[::]`, `0:0:0:0:0:0:0:0`), an explicit routable host, an empty/unspecified
+ * host, or a value we cannot parse — is reported as exposed. The cost of a
+ * missed exposure (a user ships an ops API reachable off-box) is worse than the
+ * cost of warning about a bind we did not recognise.
+ */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+/**
+ * Best-effort host half of a persisted `operationsApi.network.port` value.
+ * Returns null when the value declares no host (a bare port) or the host is
+ * unparseable; the caller reports both as exposed.
+ *
+ * Handles the forms flair and Harper write:
+ *   - `127.0.0.1:19925`  → `127.0.0.1`
+ *   - `[::1]:19925`      → `::1`   (bracketed IPv6, port stripped)
+ *   - `[::]:19925`       → `::`
+ *   - `::1:19925`        → `::1`   (bare IPv6 with a trailing numeric port)
+ *   - `::`               → `::`    (bare wildcard, nothing to strip)
+ *   - `0:0:0:0:0:0:0:0`  → `0:0:0:0:0:0:0` (still not loopback — flagged)
+ *
+ * Splits on the LAST colon so an IPv6 literal keeps its port, matching
+ * `harperPortValue`. A trailing all-digit segment is treated as the port; a
+ * bare IPv6 like `::` has no trailing port, so the whole value is the host.
+ */
+function parseBindHost(str) {
+    if (str.startsWith("[")) {
+        const close = str.indexOf("]");
+        if (close === -1)
+            return null; // malformed bracket form — unparseable
+        return str.slice(1, close);
+    }
+    const lastColon = str.lastIndexOf(":");
+    if (lastColon === -1)
+        return null; // bare port — no host to narrow on
+    const tail = str.slice(lastColon + 1);
+    return /^\d+$/.test(tail) ? str.slice(0, lastColon) : str;
+}
+/**
+ * Decide whether a persisted `operationsApi.network.port` value (read back from
+ * harper-config.yaml) indicates an ops-API bind reachable off-box.
+ *
+ * A bare port number/numeric string is Harper's all-interfaces default (the
+ * pre-flair#670 behavior, or an install that predates the fix and has not been
+ * re-`init`ed). A `host:port` string narrows the bind ONLY when the host is
+ * loopback — a wildcard (`0.0.0.0:19925`, `[::]:19925`, `::19925`) is still
+ * all-interfaces, and is flagged (flair#852). Empty/unspecified and unparseable
+ * values are flagged too.
+ */
+export function detectOpsApiAllInterfacesBind(portValue) {
+    if (portValue === undefined || portValue === null)
+        return { allInterfaces: false, boundHost: null };
+    const str = String(portValue).trim();
+    if (str === "")
+        return { allInterfaces: false, boundHost: null };
+    const host = parseBindHost(str);
+    if (host !== null && LOOPBACK_HOSTS.has(host.toLowerCase())) {
+        return { allInterfaces: false, boundHost: host };
+    }
+    return { allInterfaces: true, boundHost: null };
+}
+const OPS_API_BIND_REMEDY = "Single-host installs don't need this reachable off-box. Fix: flair init && flair restart " +
+    "(rebinds to loopback + domain socket; re-init reuses your existing admin password, so this is " +
+    "safe on a running install — pass --ops-bind for deliberate remote admin)";
+/**
+ * The ops-API bind finding for a parsed harper-config, or null when the config
+ * declares no ops port (nothing to report). This is the single source of truth
+ * `flair doctor` and `flair status` both call, so they cannot disagree about
+ * the same instance.
+ */
+export function opsApiBindFinding(harperConfig) {
+    const portValue = harperConfig?.operationsApi?.network?.port;
+    if (portValue === undefined || portValue === null || String(portValue).trim() === "")
+        return null;
+    const { allInterfaces, boundHost } = detectOpsApiAllInterfacesBind(portValue);
+    return {
+        allInterfaces,
+        portValue,
+        boundHost,
+        message: `Ops API bound to all interfaces (${String(portValue)})`,
+        remedy: OPS_API_BIND_REMEDY,
+    };
+}

package/dist/lib/owned-pins.js

@@ -0,0 +1,219 @@
+/**
+ * owned-pins.ts — flair#1485
+ *
+ * The single catalogue of files `flair init` / `flair hook install` write a
+ * pinned `@tpsdev-ai/flair-mcp@<version>` into. `flair upgrade` refreshes
+ * every entry that is already wired; `flair doctor` reads the same list to
+ * decide whether a pin is current.
+ *
+ * Two kinds:
+ *   mcp-client         — ALL_CLIENTS kind:"mcp" config paths
+ *   session-start-hook — SUPPORTED_HARNESSES hook settings paths
+ *
+ * Adding a client to ALL_CLIENTS or a harness to SUPPORTED_HARNESSES adds
+ * it here automatically — no second list to forget on the next upgrade.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { ALL_CLIENTS, clientConfigPath, } from "../install/clients.js";
+import { checkSessionStartHook, extractFlairMcpPin, isFlairHookCommand, readClientMcpBlock, } from "../doctor-client.js";
+import { hookInstallHint, hookSettingsPath, repinSessionStartHook, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { flairCliVersion, isResolvedVersion } from "./mcp-spec.js";
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function displayHomePath(homeDir, path) {
+    if (path.startsWith(homeDir))
+        return "~" + path.slice(homeDir.length);
+    return path;
+}
+/**
+ * Every file Flair pins. Order: MCP clients (registry order), then hooks
+ * (harness registry order). Upgrade and doctor both iterate this.
+ */
+export function listOwnedPinTargets(homeDir) {
+    return withHome(homeDir, () => {
+        const targets = [];
+        for (const client of ALL_CLIENTS) {
+            if (client.kind !== "mcp")
+                continue;
+            const path = clientConfigPath(client.id);
+            targets.push({
+                kind: "mcp-client",
+                id: client.id,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        for (const harness of SUPPORTED_HARNESSES) {
+            const path = hookSettingsPath(homeDir, harness);
+            targets.push({
+                kind: "session-start-hook",
+                id: harness,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        return targets;
+    });
+}
+function readFileText(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readOwnedPin(target, homeDir) {
+    if (target.kind === "session-start-hook") {
+        const hook = checkSessionStartHook(homeDir, target.path);
+        const present = !!(hook.present && hook.command && isFlairHookCommand(hook.command));
+        return {
+            target,
+            present,
+            pin: present ? extractFlairMcpPin(hook.command ?? "") : null,
+        };
+    }
+    const block = readClientMcpBlock(target.id, homeDir);
+    const text = readFileText(target.path) ?? "";
+    return {
+        target,
+        present: block.present,
+        pin: block.present ? extractFlairMcpPin(text) : null,
+    };
+}
+export function readOwnedPins(homeDir) {
+    return listOwnedPinTargets(homeDir).map((t) => readOwnedPin(t, homeDir));
+}
+/**
+ * Wired pins whose concrete version is not the installed CLI version.
+ * Unpinned / absent entries are not stale — they are a different check.
+ */
+export function staleOwnedPins(homeDir, expectedVersion = flairCliVersion()) {
+    if (!isResolvedVersion(expectedVersion))
+        return [];
+    return readOwnedPins(homeDir).filter((r) => r.present && r.pin !== null && r.pin !== expectedVersion);
+}
+export function staleSessionStartHookPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "session-start-hook");
+}
+export function staleMcpClientPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "mcp-client");
+}
+/**
+ * What `flair upgrade` prints from a refresh result.
+ *
+ * A failed `client.wire` is `action: "skip"` + `ok: false` (same shape as a
+ * fail-closed hook re-pin). Filtering on `action !== "skip"` alone dropped
+ * that failure, left the pin stale, and printed nothing (Bugbot on #1485).
+ * Failures always surface. MCP no-ops/updates still print; hook no-ops stay quiet.
+ */
+export function ownedPinRefreshShouldReport(r) {
+    if (!r.ok)
+        return true;
+    if (r.target.kind === "mcp-client")
+        return r.action !== "skip";
+    return r.action === "update";
+}
+export function staleHookRemedy(readings) {
+    const harnesses = readings
+        .filter((r) => r.target.kind === "session-start-hook")
+        .map((r) => r.target.id);
+    if (harnesses.length === 0)
+        return "flair hook install";
+    return [...new Set(harnesses)].map((h) => hookInstallHint(h)).join(" ; ");
+}
+/**
+ * Refresh every already-wired owned pin to the running CLI's spec.
+ *
+ * MCP client pins need `agentId` (the wire functions rewrite the env block).
+ * SessionStart hooks do not — `repinSessionStartHook` reads the agent from
+ * the existing command. A missing agentId therefore skips MCP only; it must
+ * not skip hooks (that was the early-return hole in the inline upgrade path).
+ *
+ * NEVER adds a hook or wires a new client.
+ */
+export function refreshOwnedPins(opts) {
+    const { homeDir } = opts;
+    const flairUrl = opts.flairUrl ?? "http://127.0.0.1:9926";
+    const agentId = opts.agentId ?? null;
+    const targets = listOwnedPinTargets(homeDir);
+    const results = [];
+    return withHome(homeDir, () => {
+        for (const target of targets) {
+            if (target.kind === "session-start-hook") {
+                const harness = target.id;
+                const repin = repinSessionStartHook(homeDir, harness);
+                results.push({
+                    target,
+                    action: repin.action,
+                    ok: repin.ok,
+                    message: repin.message,
+                });
+                continue;
+            }
+            const block = readClientMcpBlock(target.id, homeDir);
+            if (!block.present) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not wired — skip`,
+                });
+                continue;
+            }
+            if (!agentId) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: no agent id — skip MCP pin refresh`,
+                });
+                continue;
+            }
+            const client = ALL_CLIENTS.find((c) => c.id === target.id);
+            if (!client) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not in client registry — skip`,
+                });
+                continue;
+            }
+            const env = {
+                FLAIR_AGENT_ID: agentId,
+                FLAIR_URL: flairUrl,
+                FLAIR_CLIENT: target.id,
+            };
+            const before = extractFlairMcpPin(readFileText(target.path) ?? "");
+            const wired = client.wire(env);
+            const after = extractFlairMcpPin(readFileText(target.path) ?? "");
+            // Failed write stays skip+ok:false (fail-closed, like hook re-pin).
+            // ownedPinRefreshShouldReport treats !ok as printable — do not recode
+            // this as a quiet skip.
+            const action = !wired.ok ? "skip"
+                : before !== after ? "update"
+                    : "noop";
+            results.push({
+                target,
+                action,
+                ok: wired.ok,
+                message: wired.message,
+            });
+        }
+        return results;
+    });
+}

package/dist/lib/stabilize-mqtt-network.js

@@ -0,0 +1,123 @@
+/**
+ * stabilize-mqtt-network.ts — keep mqtt.network key order settled (flair#1586 / #1581).
+ *
+ * Harper's HARPER_SET_CONFIG persist (`applyRuntimeEnvVarConfig`) does
+ * `YAML.stringify` of the in-memory object, so map key order is insertion
+ * order. First repair on a default/populate yaml writes:
+ *
+ *   mqtt.network: port, securePort, mtls
+ *
+ * A later direct spawn that omits SET_CONFIG (production `buildDirectSpawnEnv`)
+ * runs `cleanupRemovedEnvVar`. When SET_CONFIG first saw those ports as
+ * already-null it stored no originals, so cleanup DELETES `port` / `securePort`
+ * and the MQTT_* env vars re-add them after the surviving `mtls` key:
+ *
+ *   mqtt.network: mtls, port, securePort
+ *
+ * Adopt SET_CONFIG then `setNestedValue`s in place and keeps that order.
+ * `#1581` requires harper-config.yaml to be byte-identical across
+ * `doctor --fix`, so the adopt persist fails even though every value matches.
+ *
+ * This helper rewrites only the `mqtt.network` scalar lines, in the file's
+ * own indent/quoting, to the first-repair order. Fail-closed: nested maps,
+ * comments inside the map, or a shape we cannot attribute are left untouched
+ * rather than dumping the whole document (a full dump would fail #1581 on
+ * its own).
+ */
+import { load as parseYaml } from "js-yaml";
+const PREFERRED_MQTT_NETWORK_KEYS = ["port", "securePort", "mtls"];
+export function stabilizeMqttNetworkKeyOrder(text) {
+    let parsed;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch {
+        return { text, changed: false };
+    }
+    const net = parsed && typeof parsed === "object"
+        ? parsed.mqtt?.network
+        : undefined;
+    if (!net || typeof net !== "object" || Array.isArray(net)) {
+        return { text, changed: false };
+    }
+    const keys = Object.keys(net);
+    const preferred = PREFERRED_MQTT_NETWORK_KEYS.filter((k) => Object.prototype.hasOwnProperty.call(net, k));
+    const rest = keys.filter((k) => !preferred.includes(k));
+    const wanted = [...preferred, ...rest];
+    if (wanted.length === 0 || keys.every((k, i) => k === wanted[i])) {
+        return { text, changed: false };
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const endsWithEol = text.endsWith("\n");
+    const lines = text.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+    let mqttIdx = -1;
+    let mqttIndent = "";
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^([ \t]*)mqtt:\s*$/);
+        if (m) {
+            mqttIdx = i;
+            mqttIndent = m[1];
+            break;
+        }
+    }
+    if (mqttIdx < 0)
+        return { text, changed: false };
+    let netIdx = -1;
+    let netIndent = "";
+    for (let i = mqttIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const indent = lines[i].match(/^[ \t]*/)?.[0] ?? "";
+        if (indent.length <= mqttIndent.length)
+            break;
+        const m = lines[i].match(/^([ \t]*)network:\s*$/);
+        if (m) {
+            netIdx = i;
+            netIndent = m[1];
+            break;
+        }
+    }
+    if (netIdx < 0)
+        return { text, changed: false };
+    const items = [];
+    let bodyEnd = netIdx + 1;
+    for (let i = netIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "")
+            return { text, changed: false };
+        if (trimmed.startsWith("#"))
+            return { text, changed: false };
+        const indent = lines[i].match(/^[ \t]*/)?.[0] ?? "";
+        if (indent.length <= netIndent.length) {
+            bodyEnd = i;
+            break;
+        }
+        const keyMatch = lines[i].match(/^[ \t]+([^:#\s]+):\s*/);
+        if (!keyMatch)
+            return { text, changed: false };
+        const next = lines[i + 1];
+        if (next) {
+            const nextTrim = next.trim();
+            if (nextTrim !== "" && !nextTrim.startsWith("#")) {
+                const nextIndent = next.match(/^[ \t]*/)?.[0] ?? "";
+                if (nextIndent.length > indent.length)
+                    return { text, changed: false };
+            }
+        }
+        items.push({ key: keyMatch[1], line: lines[i] });
+        bodyEnd = i + 1;
+    }
+    if (items.length === 0)
+        return { text, changed: false };
+    const fileKeys = items.map((it) => it.key);
+    if (fileKeys.length !== wanted.length || wanted.some((k) => !fileKeys.includes(k))) {
+        return { text, changed: false };
+    }
+    if (fileKeys.every((k, i) => k === wanted[i]))
+        return { text, changed: false };
+    const byKey = new Map(items.map((it) => [it.key, it.line]));
+    const newBody = wanted.map((k) => byKey.get(k));
+    const newLines = [...lines.slice(0, netIdx + 1), ...newBody, ...lines.slice(bodyEnd)];
+    return { text: newLines.join(eol) + (endsWithEol ? eol : ""), changed: true };
+}