@jmfederico/pi-web 1.202608.1 → 1.202609.0

package/dist/cli.js

@@ -7,13 +7,16 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultPiWebConfigPath, defaultPiWebDataDir, examplePiWebConfig } from "./config.js";
 import { piWebDockerCommand } from "./docker/piWebDockerCommandPlan.js";
+import { ownEnvironmentValue } from "./environment.js";
 import { runPluginRecoveryCli } from "./pluginRecoveryCli.js";
-import { packageVersion, printPiWebVersionReport } from "./piWebVersionReport.js";
+import { packageVersion, printPiWebVersionReport, probeRunningComponentReady, runningComponentsReady, } from "./piWebVersionReport.js";
 import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck } from "./server/diagnostics/nodePtySpawnHelper.js";
 import { checkNodePtyNativeModule, formatNodePtyNativeModuleCheck } from "./server/diagnostics/nodePtyNativeModule.js";
 import { installNativeServiceCandidate, nativeServiceInstallFailureNeedsPathAdvice, } from "./nativeServices/serviceInstall.js";
+import { launchdBootoutArgs, launchdServiceTarget, orderServices, performServiceAction, serviceStartOrder, serviceStopOrder, settleLaunchdServiceUnload, startLaunchdService, } from "./nativeServices/serviceAction.js";
 import { minimumSupportedNodeVersion, nativeServiceManagerRefs, productionNativeServiceIds, } from "./nativeServices/servicePlan.js";
-import { formatNativeServiceDoctorResult, inferInstalledNativeServiceMode, inspectInstalledDevelopmentServiceInput, inspectInstalledProductionServiceContext, runNativeServiceDoctor, } from "./nativeServices/serviceDoctor.js";
+import { inspectInstalledNativeServiceDefinitions, } from "./nativeServices/installedServiceDefinitions.js";
+import { formatNativeServiceDoctorResult, inferInstalledNativeServiceMode, inspectInstalledDevelopmentServiceInput, inspectInstalledProductionServiceContext, runNativeServiceDoctor, selectManagedNativeServiceConfig, } from "./nativeServices/serviceDoctor.js";
 import { createNativeServiceAuthoritativeProbe, nativeServicePrerequisiteShellCheck, } from "./nativeServices/serviceProbe.js";
 import { renderLaunchdPlist, renderSystemdUnit } from "./nativeServices/serviceRendering.js";
 const PI_WEB_PACKAGE_NAME = "@jmfederico/pi-web";
@@ -26,12 +29,6 @@ const serviceRefs = {
     uiDev: { id: "uiDev", ...nativeServiceManagerRefs.uiDev },
 };
 const productionServiceIds = [...productionNativeServiceIds];
-const startServiceOrder = ["sessiond", "web", "uiDev"];
-const stopServiceOrder = ["web", "uiDev", "sessiond"];
-// Restart web/UI before sessiond: when `pi-web restart` runs in a pi-web
-// terminal (owned by sessiond), restarting sessiond kills the command, so any
-// services handled after it would never be restarted.
-const restartServiceOrder = ["web", "uiDev", "sessiond"];
 function platformLabel() {
     if (process.platform === "darwin")
         return "macOS";
@@ -57,9 +54,6 @@ function requireServiceBackend(command) {
         return backend;
     throw new Error(`\`${command}\` requires a supported per-user service manager (systemd user services or LaunchAgents) and is not supported on ${platformLabel()}.\n\n${manualRunAdvice()}`);
 }
-function supportsSystemdUserServices() {
-    return currentServiceBackend()?.kind === "systemd";
-}
 function manualRunAdvice() {
     return [
         "Run PI WEB manually from a checkout:",
@@ -91,6 +85,15 @@ function capture(command, args) {
     const stderr = outputText(result.stderr);
     return { status: result.status ?? 1, stdout: outputText(result.stdout), stderr: stderr === "" ? errorMessage : stderr };
 }
+function captureInstalledServiceDefinitionCommand(command, args) {
+    const result = spawnSync(command, args);
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        spawnError: result.error instanceof Error ? result.error.message : "",
+    };
+}
 function runQuiet(command, args) {
     return capture(command, args).status;
 }
@@ -221,21 +224,11 @@ function allServiceRefs() {
 function productionServiceRefs() {
     return serviceRefList(productionServiceIds);
 }
-function orderServiceRefs(refs, order) {
-    const byId = new Map(refs.map((ref) => [ref.id, ref]));
-    return order.flatMap((id) => {
-        const ref = byId.get(id);
-        return ref === undefined ? [] : [ref];
-    });
-}
 function startOrder(refs) {
-    return orderServiceRefs(refs, startServiceOrder);
+    return orderServices(refs, serviceStartOrder);
 }
 function stopOrder(refs) {
-    return orderServiceRefs(refs, stopServiceOrder);
-}
-function restartOrder(refs) {
-    return orderServiceRefs(refs, restartServiceOrder);
+    return orderServices(refs, serviceStopOrder);
 }
 function devRootPath() {
     return resolve(process.cwd());
@@ -300,30 +293,30 @@ async function installSystemdServices(plan) {
 function launchdDomain() {
     return `gui/${String(userInfo().uid)}`;
 }
-function launchdServiceTarget(ref) {
-    return `${launchdDomain()}/${ref.launchdLabel}`;
-}
-function launchdIsLoaded(ref) {
-    return capture("launchctl", ["print", launchdServiceTarget(ref)]).status === 0;
-}
-function launchdBootout(ref) {
-    runQuiet("launchctl", ["bootout", launchdServiceTarget(ref)]);
+function currentLaunchdServiceTarget(ref) {
+    return launchdServiceTarget(launchdDomain(), ref);
 }
-function launchdBootstrap(ref) {
-    run("launchctl", ["bootstrap", launchdDomain(), launchdPlistPath(ref)], { check: true });
-    run("launchctl", ["enable", launchdServiceTarget(ref)], { check: true });
+function launchdActionContext() {
+    return { domain: launchdDomain(), plistPath: launchdPlistPath };
 }
-function launchdStart(ref) {
-    if (!launchdIsLoaded(ref))
-        launchdBootstrap(ref);
-    run("launchctl", ["kickstart", launchdServiceTarget(ref)], { check: true });
+function serviceActionDeps(backend, probeEnvironment = process.env) {
+    return {
+        run: (command, args) => run(command, args),
+        runQuiet,
+        sleep: (ms) => new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        }),
+        isServiceRunning: (ref) => runtimeStatus(backend, ref).health === "running",
+        isComponentReady: (component) => probeRunningComponentReady(component, { configEnv: probeEnvironment }),
+    };
 }
 async function installLaunchdServices(plan) {
     const selected = new Set(plan.services.map((service) => service.id));
     await mkdir(launchdServiceDir, { recursive: true });
     await mkdir(logDir, { recursive: true });
-    for (const ref of stopOrder(allServiceRefs()))
-        launchdBootout(ref);
+    for (const ref of stopOrder(allServiceRefs())) {
+        runQuiet("launchctl", launchdBootoutArgs(currentLaunchdServiceTarget(ref)));
+    }
     for (const ref of allServiceRefs().filter((candidate) => !selected.has(candidate.id))) {
         await rm(launchdPlistPath(ref), { force: true });
     }
@@ -331,8 +324,16 @@ async function installLaunchdServices(plan) {
         const plistPath = join(launchdServiceDir, service.manager.launchdPlistName);
         await writeFile(plistPath, renderLaunchdPlist(plan, service, logDir));
     }
-    for (const service of plan.services)
-        launchdStart(serviceRefFromPlan(service.id, service.manager));
+    // Settle each bootout before deciding bootstrap vs kickstart: acting on a
+    // label launchd is still asynchronously unloading races the teardown and can
+    // lose the service entirely (the same defect the restart path had).
+    const context = launchdActionContext();
+    const deps = serviceActionDeps(plan.backend);
+    for (const service of plan.services) {
+        const ref = serviceRefFromPlan(service.id, service.manager);
+        await settleLaunchdServiceUnload(currentLaunchdServiceTarget(ref), deps);
+        startLaunchdService(ref, context, deps);
+    }
 }
 async function installNativeServices(plan) {
     if (plan.backend.kind === "systemd")
@@ -352,7 +353,7 @@ async function uninstallSystemdServices() {
 }
 async function uninstallLaunchdServices() {
     for (const ref of stopOrder(allServiceRefs())) {
-        launchdBootout(ref);
+        runQuiet("launchctl", launchdBootoutArgs(currentLaunchdServiceTarget(ref)));
         await rm(launchdPlistPath(ref), { force: true });
     }
 }
@@ -446,7 +447,7 @@ export function launchdRuntimeDetails(output) {
     return { state, detail, pid };
 }
 function launchdRuntimeStatus(backend, ref) {
-    const target = launchdServiceTarget(ref);
+    const target = currentLaunchdServiceTarget(ref);
     const filePath = serviceFilePath(backend, ref);
     if (!serviceFileExists(backend, ref))
         return makeServiceRuntimeStatus(ref, "not-installed", "not installed", target, filePath);
@@ -612,40 +613,27 @@ async function uninstall() {
     await uninstallNativeServices(backend);
     console.log(`PI WEB ${backend.label} removed. Production and development service files were removed; config and data were left in place.`);
 }
-function systemdServiceAction(action, refs) {
-    const orderedRefs = action === "stop" ? stopOrder(refs) : action === "restart" ? restartOrder(refs) : startOrder(refs);
-    run("systemctl", ["--user", action, ...orderedRefs.map((ref) => ref.systemdName)], { check: true });
-}
-function launchdServiceAction(action, refs) {
-    if (action === "stop") {
-        for (const ref of stopOrder(refs))
-            launchdBootout(ref);
-        return;
-    }
-    if (action === "restart") {
-        // Restart each service fully (bootout + start) before moving to the next,
-        // so the web/UI services are back up before sessiond is restarted.
-        for (const ref of restartOrder(refs)) {
-            launchdBootout(ref);
-            launchdStart(ref);
-        }
-        return;
-    }
-    for (const ref of startOrder(refs))
-        launchdStart(ref);
-}
-function serviceAction(action) {
+async function serviceAction(action) {
     const backend = requireServiceBackend(`pi-web ${action}`);
     if (action === "status") {
         if (!printServiceStatusReport(backend))
             process.exitCode = 1;
         return;
     }
+    await performLifecycleServiceAction(backend, action, process.env);
+}
+async function performLifecycleServiceAction(backend, action, probeEnvironment) {
     const refs = installedServiceRefs(backend);
-    if (backend.kind === "systemd")
-        systemdServiceAction(action, refs);
-    else
-        launchdServiceAction(action, refs);
+    const input = { backend, action, refs, launchdContext: launchdActionContext() };
+    const result = await performServiceAction(input, serviceActionDeps(backend, probeEnvironment));
+    if (result.unreadyServices.length > 0) {
+        for (const ref of result.unreadyServices) {
+            const target = backend.kind === "systemd" ? ref.systemdName : currentLaunchdServiceTarget(ref);
+            console.log(`✗ ${serviceDisplayName(ref)} did not become ready (${target}).`);
+        }
+        console.log("  Check `pi-web status` and `pi-web logs` for details.");
+        process.exitCode = 1;
+    }
 }
 /** Offline restart guidance used only after a recovery config mutation. */
 export function sessionDaemonRestartPlan(options = {}) {
@@ -696,9 +684,9 @@ export function sessionDaemonRestartPlan(options = {}) {
     };
 }
 function activeDockerMode(env) {
-    if (!truthyEnvValue(env["PI_WEB_DOCKER_RUNTIME"]))
+    if (!truthyEnvValue(ownEnvironmentValue(env, "PI_WEB_DOCKER_RUNTIME")))
         return undefined;
-    if (env["PI_WEB_DOCKER_MODE"] === "dev")
+    if (ownEnvironmentValue(env, "PI_WEB_DOCKER_MODE") === "dev")
         return "dev";
     return "runtime";
 }
@@ -792,14 +780,115 @@ function printOptionalDoctorChecks() {
         console.log("  PI WEB falls back to a bounded filesystem scan when rg is unavailable.");
     }
 }
-function installedServiceDefinitions(backend, ids) {
-    return ids.map((id) => ({
+function installedServiceDefinitions(backend, ids, purpose) {
+    const sources = ids.map((id) => ({
         id,
-        contents: readFileSync(serviceFilePath(backend, serviceRefs[id]), "utf8"),
+        path: serviceFilePath(backend, serviceRefs[id]),
+        systemdName: serviceRefs[id].systemdName,
+        launchdTarget: currentLaunchdServiceTarget(serviceRefs[id]),
     }));
+    return inspectInstalledNativeServiceDefinitions(backend, sources, {
+        readFile: (path) => readFileSync(path),
+        realpath: realpathSync,
+        capture: captureInstalledServiceDefinitionCommand,
+    }, purpose);
+}
+/** Build an isolated probe environment without mutating the caller or process. */
+export function managedServiceProbeEnvironment(backend, definitions, callerEnvironment) {
+    const selection = selectManagedNativeServiceConfig(backend, definitions, ownEnvironmentValue(callerEnvironment, "PI_WEB_CONFIG"));
+    if (!selection.ok)
+        return selection;
+    if (selection.value.source === "installed") {
+        return {
+            ok: true,
+            value: { ...callerEnvironment, PI_WEB_CONFIG: selection.value.configPath },
+        };
+    }
+    if (selection.value.source === "default" && definitions.length > 0) {
+        // An own empty value preserves default resolution while masking any
+        // prototype-inherited PI_WEB_CONFIG from downstream environment lookups.
+        return { ok: true, value: { ...callerEnvironment, PI_WEB_CONFIG: "" } };
+    }
+    return { ok: true, value: callerEnvironment };
+}
+function installedServiceProbeEnvironment(backend, ids, callerEnvironment, purpose, inspectDefinitions) {
+    // The explicit caller override wins without requiring installed definitions
+    // to be readable or canonical.
+    const callerConfigPath = ownEnvironmentValue(callerEnvironment, "PI_WEB_CONFIG");
+    if (callerConfigPath !== undefined && callerConfigPath !== "") {
+        return { ok: true, value: callerEnvironment };
+    }
+    if (ids.size === 0)
+        return { ok: true, value: callerEnvironment };
+    const definitions = inspectDefinitions(backend, [...ids], purpose);
+    if (!definitions.ok)
+        return definitions;
+    return managedServiceProbeEnvironment(backend, definitions.value, callerEnvironment);
 }
-function nativeServiceDoctorTarget(backend) {
-    const ids = installedServiceIds(backend);
+function managedServiceProbeFailure(backend, message) {
+    return [
+        `Could not select managed PI_WEB_CONFIG from installed ${backend.label}: ${message}`,
+        "Repair the reported service-manager override or definition, then re-run `pi-web install` (or `pi-web install --dev`); a nonempty PI_WEB_CONFIG explicitly overrides managed config selection for this command.",
+    ].join("\n");
+}
+/**
+ * Dispatch commands whose probes may need managed config. The service-manager,
+ * definition, lifecycle, doctor, and version boundaries are injected so this
+ * exact orchestration can be tested without mutating live services or process
+ * environment.
+ */
+export async function runReadinessCliCommand(command, dependencies) {
+    if (command === "version") {
+        await dependencies.printVersion();
+        return;
+    }
+    const environment = dependencies.environment;
+    if (command === "start" || command === "restart") {
+        const backend = dependencies.requireBackend(`pi-web ${command}`);
+        const installedIds = dependencies.installedServiceIds(backend);
+        const probeEnvironment = installedServiceProbeEnvironment(backend, installedIds, environment, command, dependencies.inspectDefinitions);
+        if (!probeEnvironment.ok)
+            throw new Error(managedServiceProbeFailure(backend, probeEnvironment.message));
+        await dependencies.runLifecycle(backend, command, probeEnvironment.value);
+        return;
+    }
+    const backend = dependencies.currentBackend();
+    const installedIds = backend === undefined
+        ? new Set()
+        : dependencies.installedServiceIds(backend);
+    let versionReportOptions = { configEnv: environment };
+    let managedInspectionFailed = false;
+    if (backend !== undefined && activeDockerMode(environment) === undefined) {
+        const probeEnvironment = installedServiceProbeEnvironment(backend, installedIds, environment, "doctor", dependencies.inspectDefinitions);
+        if (probeEnvironment.ok) {
+            versionReportOptions = { configEnv: probeEnvironment.value };
+        }
+        else {
+            managedInspectionFailed = true;
+            versionReportOptions = { webEndpointError: managedServiceProbeFailure(backend, probeEnvironment.message) };
+        }
+    }
+    await dependencies.runDoctor({
+        backend,
+        installedIds,
+        environment,
+        versionReportOptions,
+        managedInspectionFailed,
+    });
+}
+function readinessCliCommandDependencies() {
+    return {
+        environment: process.env,
+        currentBackend: currentServiceBackend,
+        requireBackend: requireServiceBackend,
+        installedServiceIds,
+        inspectDefinitions: installedServiceDefinitions,
+        runLifecycle: performLifecycleServiceAction,
+        runDoctor: doctor,
+        printVersion: async () => { await printPiWebVersionReport(); },
+    };
+}
+function nativeServiceDoctorTarget(backend, ids) {
     const mode = inferInstalledNativeServiceMode(ids);
     if (mode === "ambiguous") {
         return {
@@ -824,23 +913,16 @@ function nativeServiceDoctorTarget(backend) {
             message: `installed ${mode} service set is incomplete; ${missingId} is missing.`,
         };
     }
-    let definitions;
-    try {
-        definitions = installedServiceDefinitions(backend, expectedIds);
-    }
-    catch (error) {
-        return {
-            kind: "inspection-failure",
-            message: error instanceof Error ? error.message : String(error),
-        };
-    }
+    const definitions = installedServiceDefinitions(backend, expectedIds, "doctor");
+    if (!definitions.ok)
+        return { kind: "inspection-failure", message: definitions.message };
     if (mode === "development") {
-        const inspection = inspectInstalledDevelopmentServiceInput(backend, definitions);
+        const inspection = inspectInstalledDevelopmentServiceInput(backend, definitions.value);
         return inspection.ok
             ? { kind: "installed-development", input: inspection.value }
             : { kind: "inspection-failure", message: inspection.message };
     }
-    const inspection = inspectInstalledProductionServiceContext(backend, definitions);
+    const inspection = inspectInstalledProductionServiceContext(backend, definitions.value);
     return inspection.ok
         ? {
             kind: "prospective-production",
@@ -849,8 +931,8 @@ function nativeServiceDoctorTarget(backend) {
         }
         : { kind: "inspection-failure", message: inspection.message };
 }
-async function printNativeServiceDoctorChecks(backend) {
-    const result = await runNativeServiceDoctor(nativeServiceDoctorTarget(backend), {
+async function printNativeServiceDoctorChecks(backend, installedIds) {
+    const result = await runNativeServiceDoctor(nativeServiceDoctorTarget(backend, installedIds), {
         probe: createNativeServiceAuthoritativeProbe(),
         fileExists: regularFileExists,
     });
@@ -899,11 +981,30 @@ function printPathSetupAdvice(shell = detectServiceShell()) {
         console.log("  Avoid relying on prompt hooks; PI WEB services run non-interactive login shells.");
     }
 }
-export function doctorExitCode(generalReadinessOk, nativeServicePlanOk, nodePtyRuntimeOk) {
-    return generalReadinessOk && nativeServicePlanOk && nodePtyRuntimeOk ? 0 : 1;
-}
-async function doctor() {
-    const backend = currentServiceBackend();
+/**
+ * Running components an installed deployment must keep ready: the API-serving
+ * component whenever the web or UI dev service file is installed (the version
+ * endpoint probes the API port in both modes), and the session daemon whenever
+ * its service file is installed. Docker deployments have no native service
+ * files, so the Docker runtime marker expects both components. A machine with
+ * nothing installed expects nothing: doctor's manual-run guidance stays a
+ * passing outcome there.
+ */
+export function expectedRunningComponents(installedServices, env) {
+    if (activeDockerMode(env) !== undefined)
+        return ["web", "sessiond"];
+    const expected = [];
+    if (installedServices.has("web") || installedServices.has("uiDev"))
+        expected.push("web");
+    if (installedServices.has("sessiond"))
+        expected.push("sessiond");
+    return expected;
+}
+export function doctorExitCode(generalReadinessOk, nativeServicePlanOk, nodePtyRuntimeOk, runningComponentsOk) {
+    return generalReadinessOk && nativeServicePlanOk && nodePtyRuntimeOk && runningComponentsOk ? 0 : 1;
+}
+async function doctor(context) {
+    const { backend, installedIds, environment, versionReportOptions, managedInspectionFailed } = context;
     console.log(`Platform: ${platformLabel()}`);
     console.log(`Service backend: ${backend?.label ?? "manual run only"}`);
     console.log(`Service shell: ${describeServiceShell()}`);
@@ -911,7 +1012,13 @@ async function doctor() {
         console.log(`- Native user service plan checks skipped on ${platformLabel()}; no native-service drift is reported.`);
     }
     console.log("");
-    await printPiWebVersionReport();
+    const runningVersionInfo = await printPiWebVersionReport(versionReportOptions);
+    const expectedComponents = expectedRunningComponents(installedIds, environment);
+    const runningComponentsOk = runningComponentsReady(runningVersionInfo, expectedComponents);
+    if (!runningComponentsOk) {
+        console.log("\n✗ Installed PI WEB services are unavailable or stale (see \"Running services\" above).");
+        console.log("  Run `pi-web restart`, then check `pi-web status`.");
+    }
     console.log("\nGeneral login-shell readiness (separate from native-service requirements):");
     const generalReadinessOk = runChecks(generalDoctorChecks());
     printOptionalDoctorChecks();
@@ -921,9 +1028,15 @@ async function doctor() {
     let nativeServiceReport = null;
     if (backend !== undefined) {
         console.log("\nNative service plan checks (service-manager context):");
-        nativeServiceReport = await printNativeServiceDoctorChecks(backend);
+        if (managedInspectionFailed) {
+            console.log("✗ Installed native-service plan could not be inspected consistently with the readiness probe (see \"Running services\" above).");
+            console.log("  Repair the reported service-manager definition before relying on doctor results.");
+        }
+        else {
+            nativeServiceReport = await printNativeServiceDoctorChecks(backend, installedIds);
+        }
     }
-    if (supportsSystemdUserServices()) {
+    if (backend?.kind === "systemd") {
         const linger = isLingerEnabled();
         if (linger === true) {
             console.log("✓ systemd user lingering enabled");
@@ -943,7 +1056,7 @@ async function doctor() {
     else {
         console.log(`- systemd user lingering skipped on ${platformLabel()}`);
     }
-    const nativeServicePlanOk = nativeServiceReport?.ok ?? true;
+    const nativeServicePlanOk = !managedInspectionFailed && (nativeServiceReport?.ok ?? true);
     const pathFailure = !generalReadinessOk || nativeServiceReport?.pathAdviceRecommended === true;
     if (pathFailure) {
         console.log("\nIf a command works in your terminal but fails in the service-manager check, compare the caller and manager contexts above.");
@@ -955,7 +1068,7 @@ async function doctor() {
     if (generalReadinessOk && backend === undefined) {
         console.log(`\n${manualRunAdvice()}`);
     }
-    if (doctorExitCode(generalReadinessOk, nativeServicePlanOk, nodePtyNativeModuleOk && nodePtySpawnHelperOk) !== 0)
+    if (doctorExitCode(generalReadinessOk, nativeServicePlanOk, nodePtyNativeModuleOk && nodePtySpawnHelperOk, runningComponentsOk) !== 0)
         process.exitCode = 1;
 }
 function printNodePtyNativeModuleCheck() {
@@ -999,16 +1112,15 @@ async function main() {
         await install(args);
     else if (command === "uninstall")
         await uninstall();
-    else if (command === "start" || command === "stop" || command === "restart" || command === "status")
-        serviceAction(command);
+    else if (command === "start" || command === "restart" || command === "doctor" || command === "version") {
+        await runReadinessCliCommand(command, readinessCliCommandDependencies());
+    }
+    else if (command === "stop" || command === "status")
+        await serviceAction(command);
     else if (command === "logs")
         logs();
     else if (command === "plugins")
         runPluginRecoveryCli(args, { restartPlan: (context) => sessionDaemonRestartPlan(context) });
-    else if (command === "doctor")
-        await doctor();
-    else if (command === "version")
-        await printPiWebVersionReport();
     else if (command === "--version" || command === "-v")
         console.log(packageVersion());
     else if (command === "help" || command === "--help" || command === "-h")