kandev 0.48.0 → 0.50.0

package/dist/service/linux.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLinuxService = runLinuxService;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const health_check_1 = require("./health_check");
+const install_helpers_1 = require("./install_helpers");
+const paths_1 = require("./paths");
+const templates_1 = require("./templates");
+function makeCtx(args) {
+    const isSystem = !!args.system;
+    const unitDir = isSystem ? paths_1.LINUX_SYSTEM_UNIT_DIR : (0, paths_1.linuxUserUnitDir)();
+    const systemctlArgs = isSystem ? [] : ["--user"];
+    return {
+        args,
+        systemctlArgs,
+        unitPath: node_path_1.default.join(unitDir, `${paths_1.SERVICE_NAME}.service`),
+        isSystem,
+    };
+}
+async function runLinuxService(args) {
+    if (!(0, install_helpers_1.commandExists)("systemctl")) {
+        throw new Error("systemctl not found. Linux service install requires systemd.");
+    }
+    const ctx = makeCtx(args);
+    switch (args.action) {
+        case "install":
+            return installAsync(ctx);
+        case "uninstall":
+            return uninstall(ctx);
+        case "start":
+            return runSystemctl(ctx, ["start", paths_1.SERVICE_NAME]);
+        case "stop":
+            return runSystemctl(ctx, ["stop", paths_1.SERVICE_NAME]);
+        case "restart":
+            return runSystemctl(ctx, ["restart", paths_1.SERVICE_NAME]);
+        case "status":
+            return runSystemctl(ctx, ["status", paths_1.SERVICE_NAME], { allowFailure: true });
+        case "logs":
+            return showLogs(ctx);
+        case "config":
+            // Handled by the dispatcher in index.ts before reaching the platform layer.
+            throw new Error("unreachable: config action handled in service/index.ts");
+        default: {
+            const _exhaustive = args.action;
+            throw new Error(`unhandled service action: ${_exhaustive}`);
+        }
+    }
+}
+async function installAsync(ctx) {
+    installSync(ctx);
+    await (0, health_check_1.waitForServiceHealth)(ctx.args.port, () => (0, health_check_1.dumpJournalctlLogs)({ unit: paths_1.SERVICE_NAME, isSystem: ctx.isSystem, lines: 50 }));
+}
+function installSync(ctx) {
+    const launcher = (0, paths_1.captureLauncher)();
+    const homeDir = (0, paths_1.resolveHomeDir)(ctx.args.homeDir, ctx.isSystem);
+    const logDir = (0, paths_1.resolveLogDir)(homeDir);
+    const unit = (0, templates_1.renderSystemdUnit)({
+        launcher,
+        homeDir,
+        logDir,
+        port: ctx.args.port,
+        systemUser: ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined,
+        mode: ctx.isSystem ? "system" : "user",
+    });
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(ctx.unitPath), { recursive: true });
+    const outcome = (0, install_helpers_1.writeUnitFile)(ctx.unitPath, unit);
+    runSystemctl(ctx, ["daemon-reload"]);
+    // Always run enable --now so 'install' is fully idempotent: if the user
+    // manually disabled or stopped the service, re-running install brings it
+    // back online without changing the unit file.
+    runSystemctl(ctx, ["enable", "--now", paths_1.SERVICE_NAME]);
+    console.log(outcome === "unchanged"
+        ? "[kandev] service is enabled and running"
+        : "[kandev] service enabled and started");
+    if (!ctx.isSystem && !ctx.args.noBootStart) {
+        maybePromptLinger();
+    }
+    printPostInstallHints(ctx);
+}
+function uninstall(ctx) {
+    // Disable and stop, ignoring failures since the unit may already be stopped.
+    runSystemctl(ctx, ["disable", "--now", paths_1.SERVICE_NAME], { allowFailure: true });
+    if (node_fs_1.default.existsSync(ctx.unitPath)) {
+        node_fs_1.default.unlinkSync(ctx.unitPath);
+        console.log(`[kandev] removed ${ctx.unitPath}`);
+    }
+    else {
+        console.log(`[kandev] no unit file at ${ctx.unitPath}`);
+    }
+    runSystemctl(ctx, ["daemon-reload"], { allowFailure: true });
+}
+function showLogs(ctx) {
+    const journalArgs = ctx.isSystem ? ["-u", paths_1.SERVICE_NAME] : ["--user-unit", paths_1.SERVICE_NAME];
+    if (ctx.args.follow)
+        journalArgs.push("-f");
+    else
+        journalArgs.push("-n", "200", "--no-pager");
+    const res = (0, node_child_process_1.spawnSync)("journalctl", journalArgs, { stdio: "inherit" });
+    if (res.status !== 0 && !ctx.args.follow) {
+        throw new Error(`journalctl exited with code ${res.status}`);
+    }
+}
+function runSystemctl(ctx, args, opts = {}) {
+    const argv = [...ctx.systemctlArgs, ...args];
+    const res = (0, node_child_process_1.spawnSync)("systemctl", argv, { stdio: "inherit" });
+    if (res.status !== 0 && !opts.allowFailure) {
+        throw new Error(`systemctl ${argv.join(" ")} failed with code ${res.status}`);
+    }
+}
+function lingerEnabled(user) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("loginctl", ["show-user", user, "--property=Linger"], {
+            encoding: "utf8",
+        });
+        return out.trim().toLowerCase() === "linger=yes";
+    }
+    catch {
+        // loginctl may not be available or user record missing — assume off.
+        return false;
+    }
+}
+function maybePromptLinger() {
+    const user = (0, paths_1.currentUsername)();
+    if (lingerEnabled(user)) {
+        console.log("[kandev] enable-linger already active — kandev will start at boot");
+        return;
+    }
+    console.log("");
+    console.log("[kandev] User services only run while you're logged in.");
+    console.log("[kandev] To start kandev at boot, run:");
+    console.log(`[kandev]   sudo loginctl enable-linger ${user}`);
+    console.log("[kandev] (Pass --no-boot-start to skip this notice next time.)");
+}
+function printPostInstallHints(ctx) {
+    const ctl = ctx.isSystem ? "sudo systemctl" : "systemctl --user";
+    const journal = ctx.isSystem ? "sudo journalctl" : "journalctl --user-unit";
+    console.log("");
+    console.log("[kandev] Useful commands:");
+    console.log(`[kandev]   ${ctl} status ${paths_1.SERVICE_NAME}`);
+    console.log(`[kandev]   ${ctl} restart ${paths_1.SERVICE_NAME}`);
+    console.log(`[kandev]   ${journal} ${ctx.isSystem ? "-u " : ""}${paths_1.SERVICE_NAME} -f`);
+}

package/dist/service/macos.js

@@ -0,0 +1,196 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMacosService = runMacosService;
+exports.readInstalledLogPaths = readInstalledLogPaths;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const health_check_1 = require("./health_check");
+const install_helpers_1 = require("./install_helpers");
+const paths_1 = require("./paths");
+const templates_1 = require("./templates");
+function makeCtx(args) {
+    const isSystem = !!args.system;
+    const dir = isSystem ? paths_1.MACOS_SYSTEM_DAEMON_DIR : (0, paths_1.macosUserAgentDir)();
+    const uid = node_os_1.default.userInfo().uid;
+    const domain = isSystem ? "system" : `gui/${uid}`;
+    return {
+        args,
+        plistPath: node_path_1.default.join(dir, `${paths_1.LAUNCHD_LABEL}.plist`),
+        isSystem,
+        domain,
+        target: `${domain}/${paths_1.LAUNCHD_LABEL}`,
+    };
+}
+async function runMacosService(args) {
+    if (!(0, install_helpers_1.commandExists)("launchctl")) {
+        throw new Error("launchctl not found. macOS service install requires launchd.");
+    }
+    const ctx = makeCtx(args);
+    switch (args.action) {
+        case "install":
+            return installAsync(ctx);
+        case "uninstall":
+            return uninstall(ctx);
+        case "start":
+            return startService(ctx);
+        case "stop":
+            return stopService(ctx);
+        case "restart":
+            return restartService(ctx);
+        case "status":
+            return showStatus(ctx);
+        case "logs":
+            return showLogs(ctx);
+        case "config":
+            // Handled by the dispatcher in index.ts before reaching the platform layer.
+            throw new Error("unreachable: config action handled in service/index.ts");
+        default: {
+            const _exhaustive = args.action;
+            throw new Error(`unhandled service action: ${_exhaustive}`);
+        }
+    }
+}
+async function installAsync(ctx) {
+    const { logDir } = installSync(ctx);
+    await (0, health_check_1.waitForServiceHealth)(ctx.args.port, () => (0, health_check_1.dumpLaunchdLogs)({ logDir, lines: 50 }));
+}
+function installSync(ctx) {
+    const launcher = (0, paths_1.captureLauncher)();
+    const homeDir = (0, paths_1.resolveHomeDir)(ctx.args.homeDir, ctx.isSystem);
+    const logDir = (0, paths_1.resolveLogDir)(homeDir);
+    node_fs_1.default.mkdirSync(logDir, { recursive: true });
+    const plist = (0, templates_1.renderLaunchdPlist)({
+        launcher,
+        homeDir,
+        logDir,
+        port: ctx.args.port,
+        systemUser: ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined,
+        mode: ctx.isSystem ? "system" : "user",
+    });
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(ctx.plistPath), { recursive: true });
+    const outcome = (0, install_helpers_1.writeUnitFile)(ctx.plistPath, plist);
+    // launchctl bootstrap fails if the label is already loaded — bootout first
+    // (ignoring its error if nothing was loaded). This means 'install' is
+    // idempotent: re-running it reloads the unit even if the file is unchanged,
+    // which is how we recover from a user manually unloading the service.
+    (0, node_child_process_1.spawnSync)("launchctl", ["bootout", ctx.target], { stdio: "ignore" });
+    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+    runLaunchctl(["enable", ctx.target], { allowFailure: true });
+    console.log(outcome === "unchanged"
+        ? "[kandev] service is loaded and running"
+        : "[kandev] service loaded and started");
+    printPostInstallHints(ctx, logDir);
+    return { logDir };
+}
+function uninstall(ctx) {
+    runLaunchctl(["bootout", ctx.target], { allowFailure: true });
+    if (node_fs_1.default.existsSync(ctx.plistPath)) {
+        node_fs_1.default.unlinkSync(ctx.plistPath);
+        console.log(`[kandev] removed ${ctx.plistPath}`);
+    }
+    else {
+        console.log(`[kandev] no plist at ${ctx.plistPath}`);
+    }
+}
+// `bootstrap` loads the job (start) and `bootout` fully unloads it (stop).
+// We use these instead of `kickstart` + `kill` because the plist sets
+// `KeepAlive=true` — under KeepAlive, `kill SIGTERM` does not stop the
+// service: launchd just respawns it seconds later. Only `bootout` removes
+// the job from launchd's supervision.
+//
+// start/restart both have to handle two pre-states — job loaded vs not —
+// so each begins with a bootout-then-bootstrap dance similar to installSync.
+function startService(ctx) {
+    // Idempotent: if the label is already loaded, bootstrap would fail. Bootout
+    // first so start works whether the service was previously running or stopped.
+    (0, node_child_process_1.spawnSync)("launchctl", ["bootout", ctx.target], { stdio: "ignore" });
+    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+}
+function stopService(ctx) {
+    runLaunchctl(["bootout", ctx.target], { allowFailure: true });
+}
+// `kickstart -k` atomically kills and restarts a loaded service. If the job
+// was previously stopped (bootout'd), the target no longer exists in the
+// launchd domain and kickstart fails — fall back to bootstrap to reload it.
+function restartService(ctx) {
+    const res = (0, node_child_process_1.spawnSync)("launchctl", ["kickstart", "-k", ctx.target], { stdio: "inherit" });
+    if (res.status === 0)
+        return;
+    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+}
+function showStatus(ctx) {
+    const res = (0, node_child_process_1.spawnSync)("launchctl", ["print", ctx.target], {
+        stdio: "inherit",
+    });
+    if (res.status !== 0) {
+        console.log(`[kandev] service not loaded in ${ctx.domain}`);
+    }
+}
+function showLogs(ctx) {
+    // Pull the log paths from the *installed* plist rather than recomputing
+    // from defaults — `--home-dir` is install-only, so a user who installed
+    // with a custom home dir would otherwise see "no logs yet" at the wrong
+    // location while logs accumulate at the real path.
+    const installed = readInstalledLogPaths(ctx.plistPath);
+    const homeDir = (0, paths_1.resolveHomeDir)(ctx.args.homeDir, ctx.isSystem);
+    const fallbackDir = (0, paths_1.resolveLogDir)(homeDir);
+    const outPath = installed?.out ?? node_path_1.default.join(fallbackDir, "service.out");
+    const errPath = installed?.err ?? node_path_1.default.join(fallbackDir, "service.err");
+    const tailArgs = ctx.args.follow ? ["-f", "-n", "200"] : ["-n", "200"];
+    const targets = [outPath, errPath].filter((p) => node_fs_1.default.existsSync(p));
+    if (targets.length === 0) {
+        const checkedDir = installed ? node_path_1.default.dirname(installed.err) : fallbackDir;
+        console.log(`[kandev] no logs yet at ${checkedDir}`);
+        return;
+    }
+    (0, node_child_process_1.spawnSync)("tail", [...tailArgs, ...targets], { stdio: "inherit" });
+}
+/**
+ * Pull the literal StandardOutPath / StandardErrorPath values out of an
+ * installed plist. Plist XML is rigidly formatted by our renderer, so a
+ * regex match is enough — avoids pulling in a plist parser for two strings.
+ * Returns null when the plist is missing or doesn't contain the keys.
+ */
+function readInstalledLogPaths(plistPath) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(plistPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const outMatch = /<key>StandardOutPath<\/key>\s*<string>([^<]+)<\/string>/.exec(content);
+    const errMatch = /<key>StandardErrorPath<\/key>\s*<string>([^<]+)<\/string>/.exec(content);
+    if (!outMatch || !errMatch)
+        return null;
+    // `renderLaunchdPlist` runs values through `escapeXml`, so a path containing
+    // `&`, `<`, etc. is stored escaped in the plist. Decode before returning so
+    // the caller can stat/tail the actual file on disk.
+    return { out: unescapeXml(outMatch[1]), err: unescapeXml(errMatch[1]) };
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&"); // last — must not re-decode a `&amp;amp;`-style sequence
+}
+function runLaunchctl(args, opts = {}) {
+    const res = (0, node_child_process_1.spawnSync)("launchctl", args, { stdio: "inherit" });
+    if (res.status !== 0 && !opts.allowFailure) {
+        throw new Error(`launchctl ${args.join(" ")} failed with code ${res.status}`);
+    }
+}
+function printPostInstallHints(ctx, logDir) {
+    console.log("");
+    console.log("[kandev] Useful commands:");
+    console.log(`[kandev]   launchctl print ${ctx.target}`);
+    console.log(`[kandev]   kandev service restart${ctx.isSystem ? " --system" : ""}`);
+    console.log(`[kandev]   tail -f ${node_path_1.default.join(logDir, "service.err")}`);
+}

package/dist/service/paths.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACOS_SYSTEM_DAEMON_DIR = exports.LINUX_SYSTEM_UNIT_DIR = exports.LAUNCHD_LABEL = exports.SERVICE_NAME = void 0;
+exports.linuxUserUnitDir = linuxUserUnitDir;
+exports.linuxUserUnitPath = linuxUserUnitPath;
+exports.linuxSystemUnitPath = linuxSystemUnitPath;
+exports.macosUserAgentDir = macosUserAgentDir;
+exports.macosUserPlistPath = macosUserPlistPath;
+exports.macosSystemPlistPath = macosSystemPlistPath;
+exports.captureLauncher = captureLauncher;
+exports.resolveHomeDir = resolveHomeDir;
+exports.resolveLogDir = resolveLogDir;
+exports.currentUsername = currentUsername;
+exports.resolveServiceUser = resolveServiceUser;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("../constants");
+/** Service unit/plist locations. Single source of truth for where kandev */
+/** writes/reads its unit files — linux.ts, macos.ts, config.ts, stale_check.ts */
+/** all consume these. Exposed as functions (not eager constants) so tests can */
+/** mock `os.homedir()` between cases. */
+exports.SERVICE_NAME = "kandev";
+exports.LAUNCHD_LABEL = "com.kdlbs.kandev";
+exports.LINUX_SYSTEM_UNIT_DIR = "/etc/systemd/system";
+exports.MACOS_SYSTEM_DAEMON_DIR = "/Library/LaunchDaemons";
+function linuxUserUnitDir() {
+    return node_path_1.default.join(node_os_1.default.homedir(), ".config", "systemd", "user");
+}
+function linuxUserUnitPath() {
+    return node_path_1.default.join(linuxUserUnitDir(), `${exports.SERVICE_NAME}.service`);
+}
+function linuxSystemUnitPath() {
+    return node_path_1.default.join(exports.LINUX_SYSTEM_UNIT_DIR, `${exports.SERVICE_NAME}.service`);
+}
+function macosUserAgentDir() {
+    return node_path_1.default.join(node_os_1.default.homedir(), "Library", "LaunchAgents");
+}
+function macosUserPlistPath() {
+    return node_path_1.default.join(macosUserAgentDir(), `${exports.LAUNCHD_LABEL}.plist`);
+}
+function macosSystemPlistPath() {
+    return node_path_1.default.join(exports.MACOS_SYSTEM_DAEMON_DIR, `${exports.LAUNCHD_LABEL}.plist`);
+}
+/**
+ * Snapshot the current invocation so the service unit can faithfully reproduce it.
+ *
+ * The unit file hard-codes absolute paths because systemd/launchd start with an
+ * empty PATH and may not see the user's `node` or `kandev` shim. By recording
+ * `process.execPath` (node) and `process.argv[1]` (cli.js) at install time we
+ * avoid any PATH lookups at service-run time.
+ */
+function captureLauncher() {
+    const nodePath = process.execPath;
+    const cliEntry = resolveCliEntry();
+    const bundleDir = process.env.KANDEV_BUNDLE_DIR;
+    const version = process.env.KANDEV_VERSION;
+    const kind = bundleDir
+        ? "homebrew"
+        : cliEntry.includes(`${node_path_1.default.sep}node_modules${node_path_1.default.sep}`)
+            ? "npm"
+            : "unknown";
+    return { nodePath, cliEntry, kind, bundleDir, version };
+}
+function resolveCliEntry() {
+    const argvEntry = process.argv[1];
+    if (argvEntry && node_fs_1.default.existsSync(argvEntry)) {
+        return node_path_1.default.resolve(argvEntry);
+    }
+    throw new Error("could not resolve the kandev CLI entry path from process.argv[1]; " +
+        "rerun via the kandev binary");
+}
+/** Resolve the home directory used for the unit's KANDEV_HOME_DIR env. */
+function resolveHomeDir(override, runAsRoot) {
+    if (override) {
+        // Node's path.resolve doesn't expand `~`; users often type `--home-dir ~/foo`
+        // (especially via shell escapes that defer expansion), so do it ourselves.
+        const expanded = override === "~" || override.startsWith(`~${node_path_1.default.sep}`)
+            ? node_path_1.default.join(node_os_1.default.homedir(), override.slice(1))
+            : override;
+        return node_path_1.default.resolve(expanded);
+    }
+    if (runAsRoot) {
+        // System units default to /var/lib/kandev so root-owned data lives outside any
+        // single user's $HOME (where it would be unreachable to other users).
+        return "/var/lib/kandev";
+    }
+    return constants_1.KANDEV_HOME_DIR;
+}
+/** Absolute path to the log directory used by the unit for stdout/stderr. */
+function resolveLogDir(homeDir) {
+    return node_path_1.default.join(homeDir, "logs");
+}
+/** Current username (the EUID the CLI is running as). */
+function currentUsername() {
+    return node_os_1.default.userInfo().username;
+}
+/**
+ * Resolve which user the service should run as.
+ *
+ * For user-mode installs this is always the current user (matters for hints
+ * printed back to the user, not for the unit itself — user units don't set
+ * `User=`).
+ *
+ * For system-mode installs the CLI is typically invoked via sudo, which makes
+ * `os.userInfo().username` resolve to `root`. We prefer `SUDO_USER` so the
+ * daemon runs as the human who installed it (with access to their `~/.kandev`,
+ * git config, agent CLI credentials, etc) rather than as root.
+ *
+ * If the user genuinely wants a root-owned daemon they can run sudo with
+ * `-E` stripped or pass `--run-as root` (future flag) — but the common case
+ * (`sudo kandev service install --system`) gets the safe default.
+ */
+function resolveServiceUser(isSystem) {
+    if (!isSystem) {
+        return currentUsername();
+    }
+    const sudoUser = process.env.SUDO_USER;
+    if (sudoUser && sudoUser !== "root") {
+        return sudoUser;
+    }
+    return currentUsername();
+}

package/dist/service/stale_check.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStaleServiceUnit = detectStaleServiceUnit;
+exports.warnIfStaleServiceUnit = warnIfStaleServiceUnit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const paths_1 = require("./paths");
+const templates_1 = require("./templates");
+/**
+ * Locations of the user-mode service unit we manage. We skip system-mode
+ * locations because (a) they require sudo to fix anyway, (b) reading from
+ * arbitrary `/etc` paths from a regular launch is noisier than worth it.
+ */
+function userModeUnitPath() {
+    if (process.platform === "linux")
+        return (0, paths_1.linuxUserUnitPath)();
+    if (process.platform === "darwin")
+        return (0, paths_1.macosUserPlistPath)();
+    return null;
+}
+/**
+ * Check whether an installed user-mode service unit still references the
+ * current invocation's paths.
+ *
+ * Called once per interactive `kandev` start (skipped for `kandev service ...`
+ * commands and headless service runs). The check is intentionally cheap and
+ * silent on the happy path — only emits when a problem is detected — so it's
+ * fine to run unconditionally.
+ *
+ * Returns the warning message to print, or null when there's nothing to say.
+ */
+function detectStaleServiceUnit() {
+    const unitPath = userModeUnitPath();
+    if (!unitPath)
+        return null;
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(unitPath, "utf8");
+    }
+    catch {
+        return null; // no unit installed
+    }
+    if (!(0, templates_1.looksLikeManagedUnit)(content))
+        return null;
+    let launcher;
+    try {
+        launcher = (0, paths_1.captureLauncher)();
+    }
+    catch {
+        // captureLauncher throws when process.argv[1] is missing — extremely rare,
+        // but if it happens we can't tell whether the unit is stale or not.
+        return null;
+    }
+    // Stale = the unit's hard-coded paths no longer match the running binary.
+    // We match on substring rather than parsing the unit so the check works for
+    // both systemd Environment= lines and plist <string> entries.
+    const nodeFresh = content.includes(launcher.nodePath);
+    const cliFresh = content.includes(launcher.cliEntry);
+    if (nodeFresh && cliFresh)
+        return null;
+    return (`Your installed kandev service unit (${unitPath}) references paths that\n` +
+        `   no longer match this binary. This usually happens after upgrading via\n` +
+        `   npm or Homebrew. Re-run 'kandev service install' to refresh the unit.`);
+}
+/** Convenience: detect + print to stderr in one call. Safe to call from cli.ts. */
+function warnIfStaleServiceUnit() {
+    try {
+        const msg = detectStaleServiceUnit();
+        if (msg) {
+            process.stderr.write(`[kandev] notice: ${msg}\n`);
+        }
+    }
+    catch {
+        // Never let a diagnostic check break startup.
+    }
+}