Skip to content
Python
20.8 KB
Raw Blame
import { mkdtemp, readFile, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import {
  installUserService,
  planUserService,
  runtimeInstallLayout,
} from "@one-memory/runtime-control";
import { describe, expect, it, vi } from "vitest";
import {
  applyPreparedServiceInstall,
  inspectLaunchAgentRegistration,
  prepareServiceInstall,
  rollbackPreparedServiceInstall,
  type ServiceLifecycleDependencies,
  uninstallServicePreservingData,
} from "./service-lifecycle.js";
import { createTolerantLaunchctlRunner } from "./service-session.js";

function fixture() {
  const home = "/Users/example";
  const layout = runtimeInstallLayout({
    platform: "darwin",
    home,
    installRoot: "/Applications/MemHub/current",
    dataDir: "/Users/example/.one-memory",
  });
  const options = { uid: 501 };
  const plan = planUserService(layout, options);
  if (plan.service_file === null) throw new Error("expected ready plan");
  return { layout, options, plan };
}

function dependencies(
  overrides: Partial<ServiceLifecycleDependencies> = {},
): ServiceLifecycleDependencies {
  return {
    inspectRegistration: vi.fn(async () => ({ kind: "absent" as const })),
    inspectServiceFile: vi.fn(async () => ({ kind: "absent" as const })),
    install: vi.fn(async (_layout, options) => {
      for (const command of fixture().plan.commands.install) {
        await options.runCommand?.(command);
      }
      return fixture().plan;
    }),
    restart: vi.fn(async () => fixture().plan),
    uninstall: vi.fn(async () => "removed" as const),
    runCommand: vi.fn(async () => undefined),
    verifyRegistrationSnapshot: vi.fn(async () => undefined),
    // Default: paths are only "same" when literally equal, which matches the
    // old behaviour for positive controls and is overridden where the realpath
    // case is under test.
    sameFile: vi.fn(async (left: string, right: string) => left === right),
    serviceEnabled: vi.fn(async () => false),
    enableService: vi.fn(async () => undefined),
    disableService: vi.fn(async () => undefined),
    ...overrides,
  };
}

describe("macOS service lifecycle", () => {
  it("recognizes a registered MemHub plist through launchctl and plutil", async () => {
    const f = fixture();
    const root = await mkdtemp(path.join(tmpdir(), "memhub-launch-agent-"));
    const plistPath = path.join(root, "com.tencent.onememory.runtime.plist");
    await writeFile(plistPath, "managed plist", { mode: 0o600 });
    const capture = vi
      .fn()
      .mockResolvedValueOnce({
        code: 0,
        stdout: `gui/501/${f.plan.service_id} = {\n  path = ${plistPath}\n}`,
        stderr: "",
      })
      .mockResolvedValueOnce({
        code: 0,
        stdout: JSON.stringify({
          Label: f.plan.service_id,
          ProgramArguments: [
            f.layout.nodeCommand,
            f.layout.runtimeEntry,
            "serve",
          ],
          EnvironmentVariables: {
            ONE_MEMORY_NODE_COMMAND: f.layout.nodeCommand,
            ONE_MEMORY_RUNTIME_ENTRY: f.layout.runtimeEntry,
          },
        }),
        stderr: "",
      });

    await expect(
      inspectLaunchAgentRegistration(f.plan, f.options, capture),
    ).resolves.toMatchObject({
      kind: "managed",
      plistPath,
      content: "managed plist",
    });
    expect(capture).toHaveBeenNthCalledWith(2, [
      "/usr/bin/plutil",
      "-convert",
      "json",
      "-o",
      "-",
      plistPath,
    ]);
  });

  it("classifies a spoofed same-label plist as unmanaged", async () => {
    const f = fixture();
    const root = await mkdtemp(path.join(tmpdir(), "memhub-launch-agent-"));
    const plistPath = path.join(root, "com.tencent.onememory.runtime.plist");
    await writeFile(plistPath, "foreign plist", { mode: 0o600 });
    const capture = vi
      .fn()
      .mockResolvedValueOnce({
        code: 0,
        stdout: `path = ${plistPath}\n`,
        stderr: "",
      })
      .mockResolvedValueOnce({
        code: 0,
        stdout: JSON.stringify({
          Label: f.plan.service_id,
          ProgramArguments: ["/tmp/not-memhub", "--serve"],
        }),
        stderr: "",
      });

    await expect(
      inspectLaunchAgentRegistration(f.plan, f.options, capture),
    ).resolves.toEqual({ kind: "unmanaged", plistPath });
  });

  // P1 (2026-09-29 H13 real-machine acceptance): re-running `install --yes` on
  // an already-installed root failed with runtime_service_conflict_unmanaged_file
  // even though the on-disk plist was byte-identical. `launchctl print` reports
  // the plist's realpath (e.g. /private/tmp/... on macOS) while the plan path is
  // the unresolved one (/tmp/...), so the literal string comparison misclassified
  // a self-managed service as unknown. The comparison must be path-identity, not
  // string equality.
  it("treats launchd's resolved plist path as the same managed service", async () => {
    const f = fixture();
    const resolved =
      "/private/tmp/memhub-home/Library/LaunchAgents/com.tencent.onememory.runtime.plist";
    const unresolved =
      "/tmp/memhub-home/Library/LaunchAgents/com.tencent.onememory.runtime.plist";
    const plan = {
      ...f.plan,
      service_file: { ...f.plan.service_file!, path: unresolved },
    };
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: resolved,
        content: plan.service_file!.content,
      })),
      inspectServiceFile: vi.fn(async () => ({
        kind: "managed" as const,
        content: plan.service_file!.content,
      })),
      // The dead-simple stand-in for "these two paths point at the same file".
      sameFile: vi.fn(async () => true),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);

    expect(deps.restart).toHaveBeenCalledOnce();
    expect(deps.install).not.toHaveBeenCalled();
  });

  it("kickstarts an already registered managed service at the same plist", async () => {
    const f = fixture();
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: f.plan.service_file!.path,
        content: f.plan.service_file!.content,
      })),
      inspectServiceFile: vi.fn(async () => ({
        kind: "managed" as const,
        content: f.plan.service_file!.content,
      })),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);

    expect(deps.restart).toHaveBeenCalledOnce();
    expect(deps.install).not.toHaveBeenCalled();
  });

  it("restores an already registered App service after install health fails", async () => {
    const f = fixture();
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: f.plan.service_file!.path,
        content: f.plan.service_file!.content,
      })),
      inspectServiceFile: vi.fn(async () => ({
        kind: "managed" as const,
        content: f.plan.service_file!.content,
      })),
      serviceEnabled: vi.fn(async () => true),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);
    const rollback = vi.fn(async () => undefined);
    await rollbackPreparedServiceInstall(prepared, rollback, deps);

    expect(deps.restart).toHaveBeenCalledOnce();
    expect(deps.uninstall).toHaveBeenCalledWith(f.layout, f.options);
    expect(rollback).toHaveBeenCalledOnce();
    expect(deps.enableService).toHaveBeenCalledWith(f.layout.dataDir);
    expect(deps.install).toHaveBeenCalledOnce();
  });

  it("returns an unloaded existing plist to the unloaded state", async () => {
    const f = fixture();
    const deps = dependencies({
      inspectServiceFile: vi.fn(async () => ({
        kind: "managed" as const,
        content: f.plan.service_file!.content,
      })),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);
    const rollback = vi.fn(async () => undefined);
    await rollbackPreparedServiceInstall(prepared, rollback, deps);

    expect(deps.runCommand).toHaveBeenNthCalledWith(
      1,
      f.plan.commands.install[0],
    );
    expect(deps.runCommand).toHaveBeenNthCalledWith(2, f.plan.commands.stop[0]);
    expect(rollback).toHaveBeenCalledOnce();
    expect(deps.disableService).toHaveBeenCalledWith(f.layout.dataDir);
    expect(deps.uninstall).not.toHaveBeenCalled();
  });

  it("removes a first-time service when install health later fails", async () => {
    const f = fixture();
    const deps = dependencies();

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);
    const rollback = vi.fn(async () => undefined);
    await rollbackPreparedServiceInstall(prepared, rollback, deps);

    expect(deps.uninstall).toHaveBeenCalledOnce();
    expect(rollback).toHaveBeenCalledOnce();
    expect(deps.disableService).toHaveBeenCalledWith(f.layout.dataDir);
  });

  it("replaces a managed registration from another install root", async () => {
    const f = fixture();
    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: oldPath,
        content: "old managed plist",
      })),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);

    expect(deps.runCommand).toHaveBeenNthCalledWith(1, [
      "launchctl",
      "bootout",
      "gui/501",
      oldPath,
    ]);
    expect(deps.runCommand).toHaveBeenNthCalledWith(
      2,
      f.plan.commands.install[0],
    );
    expect(deps.verifyRegistrationSnapshot).toHaveBeenCalledWith(
      expect.objectContaining({ plistPath: oldPath }),
    );
  });

  it("restores the previous managed registration when bootstrap fails", async () => {
    const f = fixture();
    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
    const runCommand = vi
      .fn()
      .mockResolvedValueOnce(undefined)
      .mockRejectedValueOnce(new Error("bootstrap failed"))
      .mockResolvedValueOnce(undefined);
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: oldPath,
        content: "old managed plist",
      })),
      runCommand,
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await expect(applyPreparedServiceInstall(prepared, deps)).rejects.toThrow(
      "runtime_service_managed_upgrade_failed",
    );

    expect(runCommand).toHaveBeenNthCalledWith(3, [
      "launchctl",
      "bootstrap",
      "gui/501",
      oldPath,
    ]);
    expect(deps.verifyRegistrationSnapshot).toHaveBeenCalledTimes(2);
  });

  it("does not re-bootstrap a previous registration that may serve a legacy home", async () => {
    const f = fixture();
    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
    const runCommand = vi
      .fn()
      .mockResolvedValueOnce(undefined)
      .mockRejectedValueOnce(new Error("bootstrap failed"));
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: oldPath,
        content: "old managed plist",
      })),
      runCommand,
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await expect(
      applyPreparedServiceInstall(
        { ...prepared, restorePreviousOnFailure: false },
        deps,
      ),
    ).rejects.toThrow("runtime_service_replacement_failed");

    // bootout + the failed bootstrap only; the old plist is not bootstrapped.
    expect(runCommand).toHaveBeenCalledTimes(2);
    expect(runCommand).not.toHaveBeenCalledWith([
      "launchctl",
      "bootstrap",
      "gui/501",
      oldPath,
    ]);
  });

  it("removes the replacement plist and restores the previous registration", async () => {
    const f = fixture();
    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "managed" as const,
        plistPath: oldPath,
        content: "old managed plist",
      })),
      serviceEnabled: vi.fn(async () => true),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await applyPreparedServiceInstall(prepared, deps);
    const rollback = vi.fn(async () => undefined);
    await rollbackPreparedServiceInstall(prepared, rollback, deps);

    expect(deps.uninstall).toHaveBeenCalledWith(f.layout, f.options);
    expect(rollback).toHaveBeenCalledOnce();
    expect(deps.enableService).toHaveBeenCalledWith(f.layout.dataDir);
    expect(deps.runCommand).toHaveBeenLastCalledWith([
      "launchctl",
      "bootstrap",
      "gui/501",
      oldPath,
    ]);
  });

  it("rejects an unknown same-label service before any install mutation", async () => {
    const f = fixture();
    const deps = dependencies({
      inspectRegistration: vi.fn(async () => ({
        kind: "unmanaged" as const,
        plistPath: "/Library/LaunchAgents/com.tencent.onememory.runtime.plist",
      })),
    });

    await expect(
      prepareServiceInstall(f.layout, f.options, deps),
    ).rejects.toThrow("runtime_service_conflict_unmanaged_label");
    expect(deps.install).not.toHaveBeenCalled();
    expect(deps.runCommand).not.toHaveBeenCalled();
  });

  it("turns an incomplete install into an actionable service-install error", async () => {
    const f = fixture();
    const deps = dependencies({
      install: vi.fn(async () => {
        throw new Error("runtime_install_incomplete");
      }),
    });

    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
    await expect(applyPreparedServiceInstall(prepared, deps)).rejects.toThrow(
      "runtime_install_incomplete: run memhub install --yes first",
    );
  });

  it("removes only the service and preserves the selected data directory", async () => {
    const root = await mkdtemp(path.join(tmpdir(), "memhub-data-preserved-"));
    const marker = path.join(root, "must-survive.txt");
    await writeFile(marker, "user memory", "utf8");
    const layout = runtimeInstallLayout({
      platform: "darwin",
      home: "/Users/example",
      installRoot: "/Applications/MemHub/current",
      dataDir: root,
    });
    const deps = dependencies();

    await expect(
      uninstallServicePreservingData(layout, { uid: 501 }, deps),
    ).resolves.toBe("removed");
    expect(await readFile(marker, "utf8")).toBe("user memory");
  });

  // Regression (2026-09-29 H17 A8): `memhub stop` now boots the launchd label
  // out, but leaves the managed plist on disk. A later `memhub uninstall --yes`
  // re-runs `launchctl bootout`, which then exits non-zero ("Boot-out failed: 3:
  // No such process"), and `uninstallUserService` aborted before unlinking the
  // plist. The stale plist made every subsequent `install --yes` fail with
  // `runtime_service_file_exists`. The CLI injects a tolerant runner so an
  // already-unloaded label is not treated as a teardown failure.
  it("uninstalls after the service was already booted out and removes the plist", async () => {
    if (process.platform !== "darwin") return;
    const home = await mkdtemp(path.join(tmpdir(), "memhub-uninstall-"));
    const layout = runtimeInstallLayout({
      platform: "darwin",
      home,
      installRoot: path.join(home, "runtime"),
      dataDir: path.join(home, "data"),
    });
    const files = [
      layout.nodeCommand,
      layout.runtimeEntry,
      layout.coreCommand,
      layout.mcpEntryPath,
      layout.recallCliPath,
      path.join(layout.syncHookAssetsDirectory, "manifest.json"),
    ];
    for (const file of files) {
      const { mkdir } = await import("node:fs/promises");
      await mkdir(path.dirname(file), { recursive: true });
      await writeFile(file, "fixture");
    }
    const options = { uid: process.getuid?.() };
    const plan = await installUserService(layout, {
      ...options,
      runCommand: async () => undefined,
    });
    const plistPath = plan.service_file?.path as string;
    await expect(readFile(plistPath, "utf8")).resolves.toBe(
      plan.service_file?.content,
    );

    // C7 `9e10d1e` changed the uninstall semantics: a `bootout` failure is no
    // longer fatal on its own. The shared uninstaller re-probes with
    // `launchctl print` and tolerates the failure only when that probe reports
    // 113 (the label really is not loaded). The CLI injects the tolerant
    // runner, which is checked below; the tolerant runner alone (without the
    // print re-probe) is no longer the whole story.
    //
    // The reverse case must still fail: a job that is still loaded after a
    // failed bootout is a real teardown failure and must not be reported as a
    // successful uninstall.
    const withLaunchctlPrint = (code: number) => {
      // The shared uninstaller calls the real `launchctl print` through the
      // package's probe, not the injected runner, so the deterministic control
      // is a `launchctl` shim first on PATH. 113 = not loaded (tolerated);
      // 0 = still loaded (must surface the bootout failure).
      const shimDir = path.join(home, `shim-${code}`);
      const shim = path.join(shimDir, "launchctl");
      const previousPath = process.env.PATH;
      return {
        install: async () => {
          const { mkdir } = await import("node:fs/promises");
          await mkdir(shimDir, { recursive: true });
          await writeFile(
            shim,
            `#!/bin/sh\nif [ "$1" = "print" ]; then exit ${code}; fi\nexit 0\n`,
            { mode: 0o755 },
          );
          process.env.PATH = `${shimDir}:${previousPath ?? ""}`;
        },
        restore: () => {
          process.env.PATH = previousPath;
        },
      };
    };

    // 113 from `launchctl print` after a failed bootout: already stopped.
    //
    // This exact expectation only holds once C7 `9e10d1e`'s print re-probe is
    // present in `packages/runtime-control`. This branch alone has the older
    // shared package, where a plain bootout failure is still fatal, so the
    // directions are asserted where each is meaningful:
    //  - on this branch: the tolerant runner still tolerates the not-found
    //    case and refuses a genuinely unrecognized failure;
    //  - in the C7 combination: the print re-probe decides, so both the
    //    113 (tolerated) and still-loaded (fatal) cases are checked below.
    // The condition keeps the test honest in both trees instead of passing
    // for the wrong reason.
    const sharedInstallSource = await readFile(
      new URL(
        "../../../packages/runtime-control/src/service-install.ts",
        import.meta.url,
      ),
      "utf8",
    );
    const hasPrintReprobe = sharedInstallSource.includes("uninstallBootout");

    const notLoaded = withLaunchctlPrint(113);
    await notLoaded.install();
    try {
      await expect(
        uninstallServicePreservingData(layout, {
          ...options,
          runCommand: createTolerantLaunchctlRunner(async (command) => {
            if (command[1] === "bootout") {
              return {
                code: hasPrintReprobe ? 5 : 3,
                stdout: "",
                stderr: hasPrintReprobe
                  ? `Operation not permitted`
                  : `Boot-out failed: 3: No such process`,
              };
            }
            return { code: 0, stdout: "", stderr: "" };
          }),
        }),
      ).resolves.toBe("removed");
    } finally {
      notLoaded.restore();
    }
    await expect(readFile(plistPath, "utf8")).rejects.toThrow();

    // Re-create the managed plist so the reverse case starts from the same
    // state.
    const { mkdir } = await import("node:fs/promises");
    await mkdir(path.dirname(plistPath), { recursive: true, mode: 0o700 });
    await writeFile(plistPath, plan.service_file?.content as string, {
      mode: 0o600,
    });

    // `launchctl print` reports the job is still loaded (exit 0): the failed
    // bootout must surface and the plist must survive.
    const stillLoaded = withLaunchctlPrint(0);
    await stillLoaded.install();
    try {
      await expect(
        uninstallServicePreservingData(layout, {
          ...options,
          runCommand: createTolerantLaunchctlRunner(async (command) => {
            if (command[1] === "bootout") {
              return {
                code: 5,
                stdout: "",
                stderr: `Operation not permitted`,
              };
            }
            return { code: 0, stdout: "", stderr: "" };
          }),
        }),
      ).rejects.toThrow("runtime_service_command_failed");
    } finally {
      stillLoaded.restore();
    }
    await expect(readFile(plistPath, "utf8")).resolves.toBeDefined();
  });
});