@pixelbyte-software/pixcode 1.30.0

package/server/daemon-manager.js

@@ -0,0 +1,920 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { request } from 'node:http';
+import net from 'node:net';
+
+const DAEMON_SERVICE_NAME = 'pixcode.service';
+const FRONTEND_DAEMON_SERVICE_NAME = 'pixcode-frontend.service';
+const DAEMON_USER_SERVICE_PATH = path.join(os.homedir(), '.config', 'systemd', 'user', DAEMON_SERVICE_NAME);
+const DAEMON_SYSTEM_SERVICE_PATH = path.join('/etc', 'systemd', 'system', DAEMON_SERVICE_NAME);
+const FRONTEND_DAEMON_USER_SERVICE_PATH = path.join(os.homedir(), '.config', 'systemd', 'user', FRONTEND_DAEMON_SERVICE_NAME);
+const FRONTEND_DAEMON_SYSTEM_SERVICE_PATH = path.join('/etc', 'systemd', 'system', FRONTEND_DAEMON_SERVICE_NAME);
+const DEFAULT_FRONTEND_PORT = 5173;
+const DAEMON_HEALTH_TIMEOUT_MS = 60000;
+const DAEMON_HEALTH_REQUEST_TIMEOUT_MS = 4000;
+const DAEMON_HEALTH_RETRY_INTERVAL_MS = 1000;
+
+const DAEMON_SUBCOMMANDS = new Set([
+    'install',
+    'start',
+    'stop',
+    'restart',
+    'status',
+    'logs',
+    'enable',
+    'disable',
+    'uninstall',
+    'doctor',
+    'help',
+]);
+
+const DAEMON_MODES = new Set(['auto', 'user', 'system']);
+const SYSTEM_MUTATING_DAEMON_SUBCOMMANDS = new Set([
+    'install',
+    'start',
+    'stop',
+    'restart',
+    'enable',
+    'disable',
+    'uninstall',
+    'logs',
+]);
+let pixcodeBinaryAvailableCache = null;
+
+function passthroughColor(text) {
+    return text;
+}
+
+function getColorHelpers(color) {
+    if (color) {
+        return color;
+    }
+    return {
+        info: passthroughColor,
+        ok: passthroughColor,
+        warn: passthroughColor,
+        error: passthroughColor,
+        tip: passthroughColor,
+        bright: passthroughColor,
+        dim: passthroughColor,
+    };
+}
+
+function runCommand(bin, args, opts = {}) {
+    const stdio = opts.inherit ? 'inherit' : 'pipe';
+    return spawnSync(bin, args, {
+        encoding: 'utf8',
+        stdio,
+    });
+}
+
+function extractCommandError(result, fallbackMessage) {
+    if (!result) return fallbackMessage;
+    const fromError = result.error?.message?.trim();
+    if (fromError) return fromError;
+    const fromStd = (result.stderr || result.stdout || '').trim();
+    if (fromStd) return fromStd;
+    return fallbackMessage;
+}
+
+function isRootUser() {
+    return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+
+function quoteShellArg(arg) {
+    const value = String(arg);
+    if (/^[A-Za-z0-9_./:=+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function quoteSystemdArg(arg) {
+    return `"${String(arg).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+function resolveDaemonCliEntryPath(context = {}) {
+    const appRoot = context.appRoot || process.cwd();
+    const explicitCliEntry = context.cliEntry ? path.resolve(context.cliEntry) : null;
+    const argvCliEntry = process.argv[1] ? path.resolve(process.argv[1]) : null;
+    const candidatePaths = [
+        explicitCliEntry,
+        argvCliEntry,
+        path.join(appRoot, 'dist-server', 'server', 'cli.js'),
+        path.join(appRoot, 'server', 'cli.js'),
+    ].filter(Boolean);
+
+    const existingPath = candidatePaths.find(candidate => fs.existsSync(candidate));
+    if (existingPath) {
+        return existingPath;
+    }
+
+    return explicitCliEntry || argvCliEntry || path.join(appRoot, 'server', 'cli.js');
+}
+
+function hasPixcodeBinary() {
+    if (pixcodeBinaryAvailableCache !== null) {
+        return pixcodeBinaryAvailableCache;
+    }
+
+    const probe = runCommand('pixcode', ['--version']);
+    pixcodeBinaryAvailableCache = probe.status === 0;
+    return pixcodeBinaryAvailableCache;
+}
+
+function getDaemonCommandPrefix(context = {}, { forceLocal = false } = {}) {
+    if (!forceLocal && hasPixcodeBinary()) {
+        return 'pixcode';
+    }
+
+    const nodeExec = context.nodeExecPath || process.execPath || 'node';
+    const cliEntry = resolveDaemonCliEntryPath(context);
+    return `${quoteShellArg(nodeExec)} ${quoteShellArg(cliEntry)}`;
+}
+
+export function buildDaemonCliCommand({ subcommand, mode = 'system', extraArgs = [] }, context = {}) {
+    const normalizedSubcommand = String(subcommand || 'status').trim() || 'status';
+    const normalizedMode = String(mode || 'system').trim() || 'system';
+    const args = ['daemon', normalizedSubcommand, '--mode', normalizedMode, ...extraArgs.map(value => String(value))];
+    const needsSudo =
+        normalizedMode === 'system' &&
+        SYSTEM_MUTATING_DAEMON_SUBCOMMANDS.has(normalizedSubcommand) &&
+        !isRootUser();
+    const prefix = getDaemonCommandPrefix(context, { forceLocal: needsSudo });
+    const command = `${prefix} ${args.map(quoteShellArg).join(' ')}`;
+    return needsSudo ? `sudo ${command}` : command;
+}
+
+function getDaemonServicePath(mode) {
+    return mode === 'system' ? DAEMON_SYSTEM_SERVICE_PATH : DAEMON_USER_SERVICE_PATH;
+}
+
+function getFrontendServicePath(mode) {
+    return mode === 'system' ? FRONTEND_DAEMON_SYSTEM_SERVICE_PATH : FRONTEND_DAEMON_USER_SERVICE_PATH;
+}
+
+function getSystemctlArgs(mode, commandArgs) {
+    return mode === 'user' ? ['--user', ...commandArgs] : commandArgs;
+}
+
+function getJournalctlArgs(mode, commandArgs) {
+    return mode === 'user' ? ['--user', ...commandArgs] : commandArgs;
+}
+
+function parseDaemonArgs(args) {
+    const parsed = {
+        subcommand: 'status',
+        options: {
+            mode: 'system',
+        },
+    };
+
+    let i = 0;
+    if (args[0] && DAEMON_SUBCOMMANDS.has(args[0])) {
+        parsed.subcommand = args[0];
+        i = 1;
+    }
+
+    for (; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--port' || arg === '-p') {
+            parsed.options.serverPort = args[++i];
+        } else if (arg.startsWith('--port=')) {
+            parsed.options.serverPort = arg.split('=')[1];
+        } else if (arg === '--frontend-port') {
+            parsed.options.frontendPort = args[++i];
+        } else if (arg.startsWith('--frontend-port=')) {
+            parsed.options.frontendPort = arg.split('=')[1];
+        } else if (arg === '--mode' || arg === '-m') {
+            parsed.options.mode = (args[++i] || '').toLowerCase();
+        } else if (arg.startsWith('--mode=')) {
+            parsed.options.mode = (arg.split('=')[1] || '').toLowerCase();
+        } else if (arg === '--database-path') {
+            parsed.options.databasePath = args[++i];
+        } else if (arg.startsWith('--database-path=')) {
+            parsed.options.databasePath = arg.split('=')[1];
+        } else if (arg === '--help' || arg === '-h') {
+            parsed.subcommand = 'help';
+        } else {
+            parsed.options.extraArgs = parsed.options.extraArgs || [];
+            parsed.options.extraArgs.push(arg);
+        }
+    }
+
+    return parsed;
+}
+
+function buildDaemonExecStart({ appRoot, serverPort, databasePath, nodeExecPath, cliEntry }) {
+    const nodeExec = nodeExecPath || process.execPath || 'node';
+    const cliCandidate = cliEntry
+        ? path.resolve(cliEntry)
+        : (process.argv[1] ? path.resolve(process.argv[1]) : path.join(appRoot, 'dist-server', 'server', 'cli.js'));
+    const resolvedCliEntry = fs.existsSync(cliCandidate)
+        ? cliCandidate
+        : path.join(appRoot, 'dist-server', 'server', 'cli.js');
+
+    const args = [nodeExec, resolvedCliEntry, 'start', '--port', String(serverPort)];
+    if (databasePath) {
+        args.push('--database-path', databasePath);
+    }
+
+    return args.map(quoteSystemdArg).join(' ');
+}
+
+function buildDaemonServiceUnit({ appRoot, serverPort, databasePath, nodeExecPath, cliEntry }) {
+    const execStart = buildDaemonExecStart({
+        appRoot,
+        serverPort,
+        databasePath,
+        nodeExecPath,
+        cliEntry,
+    });
+    return `[Unit]
+Description=Pixcode Server
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=${appRoot}
+ExecStart=${execStart}
+Environment=HOST=0.0.0.0
+Environment=CI=true
+Environment=PIXCODE_DAEMON_MANAGED=1
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function resolveFrontendDaemonEntry(appRoot, cliEntry) {
+    const cliCandidate = cliEntry
+        ? path.resolve(cliEntry)
+        : (process.argv[1] ? path.resolve(process.argv[1]) : '');
+    const candidates = [];
+    if (cliCandidate) {
+        candidates.push(path.join(path.dirname(cliCandidate), 'vite-daemon.js'));
+    }
+    candidates.push(path.join(appRoot, 'dist-server', 'server', 'vite-daemon.js'));
+    candidates.push(path.join(appRoot, 'server', 'vite-daemon.js'));
+
+    const resolved = candidates.find(candidate => fs.existsSync(candidate));
+    if (!resolved) {
+        throw new Error(
+            `Frontend daemon entry was not found. Checked: ${candidates.join(', ')}. ` +
+            `Run "npm run build:server" or ensure server/vite-daemon.js exists.`
+        );
+    }
+    return resolved;
+}
+
+function buildFrontendDaemonExecStart({ appRoot, frontendPort, nodeExecPath, cliEntry }) {
+    const nodeExec = nodeExecPath || process.execPath || 'node';
+    const frontendEntry = resolveFrontendDaemonEntry(appRoot, cliEntry);
+    const args = [
+        nodeExec,
+        frontendEntry,
+        '--host',
+        '0.0.0.0',
+        '--port',
+        String(frontendPort),
+        '--strictPort',
+    ];
+    return args.map(quoteSystemdArg).join(' ');
+}
+
+function buildFrontendDaemonServiceUnit({ appRoot, frontendPort, nodeExecPath, cliEntry }) {
+    const execStart = buildFrontendDaemonExecStart({
+        appRoot,
+        frontendPort,
+        nodeExecPath,
+        cliEntry,
+    });
+    return `[Unit]
+Description=Pixcode Frontend (Vite Dev Server)
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=${appRoot}
+ExecStart=${execStart}
+Environment=HOST=0.0.0.0
+Environment=CI=true
+Environment=PIXCODE_DAEMON_MANAGED=1
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function normalizeState(value) {
+    const text = (value || '').trim();
+    if (!text) return 'unknown';
+    if (/No such file or directory/i.test(text)) return 'not-found';
+    return text;
+}
+
+function getServiceState(mode, serviceName) {
+    const activeRes = runCommand('systemctl', getSystemctlArgs(mode, ['is-active', serviceName]));
+    const enabledRes = runCommand('systemctl', getSystemctlArgs(mode, ['is-enabled', serviceName]));
+
+    return {
+        active: normalizeState(activeRes.stdout || activeRes.stderr),
+        enabled: normalizeState(enabledRes.stdout || enabledRes.stderr),
+    };
+}
+
+function readLogs(mode, lines = 100, inherit = false, serviceNames = [DAEMON_SERVICE_NAME]) {
+    const unitArgs = serviceNames.flatMap((serviceName) => ['-u', serviceName]);
+    const args = [...getJournalctlArgs(mode, unitArgs), '-n', String(lines), '--no-pager'];
+    return runCommand('journalctl', args, { inherit });
+}
+
+function getPortFromServiceUnit(servicePath) {
+    if (!fs.existsSync(servicePath)) return null;
+    try {
+        const content = fs.readFileSync(servicePath, 'utf8');
+        const quoted = content.match(/"--port"\s+"(\d+)"/);
+        if (quoted) return Number(quoted[1]);
+        const plain = content.match(/--port(?:\s+|=)(\d+)/);
+        if (plain) return Number(plain[1]);
+    } catch {
+        // Ignore parse errors and use fallback port.
+    }
+    return null;
+}
+
+function findLatestErrorLine(logText) {
+    if (!logText) return '';
+    const lines = logText.split('\n').map(line => line.trim()).filter(Boolean);
+    const errorLine = [...lines].reverse().find(line => /(error|failed|exception|denied|cannot|traceback)/i.test(line));
+    return errorLine || '';
+}
+
+function probeUserBus() {
+    const result = runCommand('systemctl', ['--user', 'show-environment']);
+    return {
+        ok: result.status === 0,
+        detail: extractCommandError(result, 'systemd user bus is not reachable'),
+    };
+}
+
+function probeLinger() {
+    const result = runCommand('loginctl', ['show-user', os.userInfo().username, '-p', 'Linger']);
+    if (result.status !== 0) {
+        return {
+            value: 'unknown',
+            detail: extractCommandError(result, 'Could not read linger status'),
+        };
+    }
+    const output = (result.stdout || '').trim();
+    const value = output.includes('=') ? output.split('=')[1].trim().toLowerCase() : output.toLowerCase();
+    return {
+        value: value || 'unknown',
+        detail: '',
+    };
+}
+
+function resolveDaemonMode({ requestedMode, subcommand, userBusAvailable }) {
+    if (requestedMode !== 'auto') {
+        return requestedMode;
+    }
+
+    // Auto mode is intentionally system-first to guarantee boot-time startup
+    // even without an interactive user session.
+    const systemUnitInstalled = fs.existsSync(getDaemonServicePath('system'));
+    const userUnitInstalled = fs.existsSync(getDaemonServicePath('user'));
+
+    if (systemUnitInstalled) return 'system';
+    if (subcommand === 'install') return 'system';
+    if (userUnitInstalled && userBusAvailable) return 'user';
+    return 'system';
+}
+
+function runSystemctl(mode, commandArgs, opts = {}) {
+    const result = runCommand('systemctl', getSystemctlArgs(mode, commandArgs), { inherit: opts.inherit });
+    if (result.status !== 0 && !opts.allowFailure) {
+        let errorText = extractCommandError(result, `systemctl ${commandArgs.join(' ')} failed`);
+        if (mode === 'system' && /(access denied|permission denied|must be root|interactive authentication required|not permitted)/i.test(errorText)) {
+            errorText += '\nTry rerunning this daemon operation with elevated privileges (sudo).';
+        }
+        throw new Error(errorText);
+    }
+    return result;
+}
+
+async function sleep(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function isPortReachable(port, timeoutMs = 1000) {
+    return await new Promise(resolve => {
+        const socket = net.createConnection({ host: '127.0.0.1', port: Number(port) });
+        let settled = false;
+        const done = (value) => {
+            if (settled) return;
+            settled = true;
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+    });
+}
+
+async function requestHealthOnce(port, timeoutMs = DAEMON_HEALTH_REQUEST_TIMEOUT_MS) {
+    return await new Promise((resolve, reject) => {
+        const req = request({
+            host: '127.0.0.1',
+            port: Number(port),
+            method: 'GET',
+            path: '/health',
+            timeout: timeoutMs,
+        }, (res) => {
+            res.resume();
+            resolve({ ok: true, statusCode: res.statusCode });
+        });
+
+        req.on('timeout', () => req.destroy(new Error(`Health check timed out after ${timeoutMs}ms`)));
+        req.on('error', reject);
+        req.end();
+    });
+}
+
+async function waitForHealth(port, timeoutMs = DAEMON_HEALTH_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        try {
+            return await requestHealthOnce(port);
+        } catch (error) {
+            lastError = error;
+            if (await isPortReachable(port, 700)) {
+                return { ok: true, statusCode: null, probe: 'tcp' };
+            }
+            await sleep(DAEMON_HEALTH_RETRY_INTERVAL_MS);
+        }
+    }
+    throw new Error(lastError?.message || `Service did not become healthy on port ${port}`);
+}
+
+async function healthCheckOrThrow(mode, serviceName, port, c) {
+    const state = getServiceState(mode, serviceName);
+    if (state.active !== 'active' && state.active !== 'activating') {
+        throw new Error(`Service ${serviceName} is not active (state: ${state.active})`);
+    }
+
+    try {
+        const health = await waitForHealth(port);
+        if (health.probe === 'tcp') {
+            console.log(`${c.warn('[WARN]')} HTTP /health probe delayed; TCP port ${port} is already accepting connections.`);
+        }
+    } catch (healthError) {
+        const logsResult = readLogs(mode, 50, false, [serviceName]);
+        const logText = (logsResult.stdout || logsResult.stderr || '').trim();
+        const lastErrorLine = findLatestErrorLine(logText);
+
+        if (logText) {
+            console.log(`\n${c.warn('[WARN]')} Last 50 log lines for ${serviceName}:`);
+            console.log(logText);
+        }
+
+        if (lastErrorLine) {
+            throw new Error(`Health check failed for ${serviceName}: ${healthError.message}\nLikely cause: ${lastErrorLine}`);
+        }
+        throw new Error(`Health check failed for ${serviceName}: ${healthError.message}`);
+    }
+}
+
+function ensureLinux() {
+    if (process.platform !== 'linux') {
+        throw new Error('The daemon command is supported on Linux only.');
+    }
+}
+
+function ensureSystemctl() {
+    const probe = runCommand('systemctl', ['--version']);
+    if (probe.status !== 0) {
+        throw new Error(extractCommandError(probe, 'systemctl is not available in this environment'));
+    }
+}
+
+function showDaemonHelp(c, context = {}) {
+    const usagePrefix = getDaemonCommandPrefix(context);
+    const installExample = buildDaemonCliCommand(
+        {
+            subcommand: 'install',
+            mode: 'system',
+            extraArgs: ['--port', '3001', '--frontend-port', '5173'],
+        },
+        context
+    );
+    const statusExample = buildDaemonCliCommand({ subcommand: 'status', mode: 'system' }, context);
+    const doctorExample = buildDaemonCliCommand({ subcommand: 'doctor', mode: 'auto' }, context);
+    const logsExample = buildDaemonCliCommand({ subcommand: 'logs', mode: 'system' }, context);
+    console.log(`
+${c.bright('Pixcode Daemon')} - Persistent Linux service manager
+
+Usage:
+  ${usagePrefix} daemon [subcommand] [options]
+
+Subcommands:
+  ${c.bright('install')}      Install/update unit, reload daemon, enable and start now
+  ${c.bright('start')}        Start the service
+  ${c.bright('stop')}         Stop the service (temporary; auto-start remains enabled)
+  ${c.bright('restart')}      Restart the service
+  ${c.bright('status')}       Show active/enabled state
+  ${c.bright('logs')}         Show recent service logs
+  ${c.bright('enable')}       Enable auto-start at boot
+  ${c.bright('disable')}      Disable auto-start at boot
+  ${c.bright('uninstall')}    Stop, disable, and remove the service unit
+  ${c.bright('doctor')}       Run diagnostics (bus, linger, units, state, port, logs)
+  ${c.bright('help')}         Show this help
+
+Options:
+  -p, --port <port>           Set service server port (default: 3001)
+  --frontend-port <port>      Set frontend Vite port (default: 5173)
+  -m, --mode <mode>           Service mode: user | system | auto (default: system)
+  --database-path <path>      Set service database path
+
+Examples:
+  $ ${installExample}
+  $ ${statusExample}
+  $ ${doctorExample}
+  $ ${logsExample}
+`);
+}
+
+export function hasInstalledDaemonUnit() {
+    return (
+        fs.existsSync(DAEMON_USER_SERVICE_PATH) ||
+        fs.existsSync(DAEMON_SYSTEM_SERVICE_PATH) ||
+        fs.existsSync(FRONTEND_DAEMON_USER_SERVICE_PATH) ||
+        fs.existsSync(FRONTEND_DAEMON_SYSTEM_SERVICE_PATH)
+    );
+}
+
+export async function handleDaemonCommand(args, context = {}) {
+    const c = getColorHelpers(context.color);
+    const parsed = parseDaemonArgs(args);
+    const appRoot = context.appRoot || process.cwd();
+    const daemonCommandContext = {
+        appRoot,
+        cliEntry: context.cliEntry,
+        nodeExecPath: context.nodeExecPath,
+    };
+
+    if (parsed.options.extraArgs?.length) {
+        showDaemonHelp(c, daemonCommandContext);
+        throw new Error(`Unknown daemon arguments: ${parsed.options.extraArgs.join(' ')}`);
+    }
+
+    if (parsed.subcommand === 'help') {
+        showDaemonHelp(c, daemonCommandContext);
+        return;
+    }
+
+    if (!DAEMON_MODES.has(parsed.options.mode)) {
+        throw new Error(`Invalid daemon mode "${parsed.options.mode}". Use one of: auto, user, system.`);
+    }
+
+    ensureLinux();
+    ensureSystemctl();
+
+    const defaultPort = context.defaultPort || process.env.SERVER_PORT || process.env.PORT || '3001';
+    const defaultFrontendPort = context.defaultFrontendPort || process.env.VITE_PORT || String(DEFAULT_FRONTEND_PORT);
+    const configuredPort = parsed.options.serverPort || defaultPort;
+    const configuredFrontendPort = parsed.options.frontendPort || defaultFrontendPort;
+    const databasePath = parsed.options.databasePath || process.env.DATABASE_PATH || '';
+
+    const portNum = Number(configuredPort);
+    if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+        throw new Error(`Invalid port "${configuredPort}". Expected an integer between 1 and 65535.`);
+    }
+    const frontendPortNum = Number(configuredFrontendPort);
+    if (!Number.isInteger(frontendPortNum) || frontendPortNum < 1 || frontendPortNum > 65535) {
+        throw new Error(`Invalid frontend port "${configuredFrontendPort}". Expected an integer between 1 and 65535.`);
+    }
+
+    const userBus = probeUserBus();
+    const mode = resolveDaemonMode({
+        requestedMode: parsed.options.mode,
+        subcommand: parsed.subcommand,
+        userBusAvailable: userBus.ok,
+    });
+    const servicePath = getDaemonServicePath(mode);
+    const frontendServicePath = getFrontendServicePath(mode);
+    const effectivePort = getPortFromServiceUnit(servicePath) || portNum;
+    const effectiveFrontendPort = getPortFromServiceUnit(frontendServicePath) || frontendPortNum;
+
+    if (mode === 'user' && !userBus.ok) {
+        const installSystemCommand = buildDaemonCliCommand(
+            { subcommand: 'install', mode: 'system' },
+            daemonCommandContext
+        );
+        throw new Error(
+            `Could not connect to your systemd user session.\n${userBus.detail}\n` +
+            `Try ${c.bright(installSystemCommand)} or enable user linger: ${c.bright(`sudo loginctl enable-linger ${os.userInfo().username}`)}`
+        );
+    }
+
+    if (parsed.subcommand === 'doctor') {
+        const linger = probeLinger();
+        const userUnitInstalled = fs.existsSync(getDaemonServicePath('user'));
+        const userFrontendUnitInstalled = fs.existsSync(getFrontendServicePath('user'));
+        const systemUnitInstalled = fs.existsSync(getDaemonServicePath('system'));
+        const systemFrontendUnitInstalled = fs.existsSync(getFrontendServicePath('system'));
+        const selectedModePort = getPortFromServiceUnit(servicePath) || portNum;
+        const selectedModeFrontendPort = getPortFromServiceUnit(frontendServicePath) || frontendPortNum;
+        const portReachable = await isPortReachable(selectedModePort);
+        const frontendPortReachable = await isPortReachable(selectedModeFrontendPort);
+        const userState = userBus.ok
+            ? {
+                backend: getServiceState('user', DAEMON_SERVICE_NAME),
+                frontend: getServiceState('user', FRONTEND_DAEMON_SERVICE_NAME),
+            }
+            : {
+                backend: { active: 'unavailable', enabled: 'unavailable' },
+                frontend: { active: 'unavailable', enabled: 'unavailable' },
+            };
+        const systemState = {
+            backend: getServiceState('system', DAEMON_SERVICE_NAME),
+            frontend: getServiceState('system', FRONTEND_DAEMON_SERVICE_NAME),
+        };
+        const logsResult = readLogs(mode, 50, false, [DAEMON_SERVICE_NAME, FRONTEND_DAEMON_SERVICE_NAME]);
+        const logsText = (logsResult.stdout || logsResult.stderr || '').trim();
+        const lastErrorLine = findLatestErrorLine(logsText);
+
+        console.log(`\n${c.bright('Pixcode Daemon Doctor')}\n`);
+        console.log(`${c.info('[INFO]')} Requested mode: ${c.bright(parsed.options.mode)}`);
+        console.log(`${c.info('[INFO]')} Resolved mode:  ${c.bright(mode)}`);
+        console.log(`${c.info('[INFO]')} user-bus:       ${userBus.ok ? c.ok('ok') : c.warn('unavailable')}`);
+        if (!userBus.ok) {
+            console.log(`       ${c.dim(userBus.detail)}`);
+        }
+        console.log(`${c.info('[INFO]')} linger:         ${c.bright(linger.value)}${linger.detail ? ` ${c.dim(`(${linger.detail})`)}` : ''}`);
+        console.log(`${c.info('[INFO]')} user backend:   ${userUnitInstalled ? c.ok('installed') : c.warn('missing')} (${c.dim(getDaemonServicePath('user'))})`);
+        console.log(`${c.info('[INFO]')} user frontend:  ${userFrontendUnitInstalled ? c.ok('installed') : c.warn('missing')} (${c.dim(getFrontendServicePath('user'))})`);
+        console.log(`${c.info('[INFO]')} system backend: ${systemUnitInstalled ? c.ok('installed') : c.warn('missing')} (${c.dim(getDaemonServicePath('system'))})`);
+        console.log(`${c.info('[INFO]')} system frontend:${systemFrontendUnitInstalled ? c.ok('installed') : c.warn('missing')} (${c.dim(getFrontendServicePath('system'))})`);
+        console.log(`${c.info('[INFO]')} user state:     backend active=${c.bright(userState.backend.active)} enabled=${c.bright(userState.backend.enabled)} | frontend active=${c.bright(userState.frontend.active)} enabled=${c.bright(userState.frontend.enabled)}`);
+        console.log(`${c.info('[INFO]')} system state:   backend active=${c.bright(systemState.backend.active)} enabled=${c.bright(systemState.backend.enabled)} | frontend active=${c.bright(systemState.frontend.active)} enabled=${c.bright(systemState.frontend.enabled)}`);
+        console.log(`${c.info('[INFO]')} backend port:   ${c.bright(String(selectedModePort))} (${portReachable ? c.ok('reachable') : c.warn('not reachable')})`);
+        console.log(`${c.info('[INFO]')} frontend port:  ${c.bright(String(selectedModeFrontendPort))} (${frontendPortReachable ? c.ok('reachable') : c.warn('not reachable')})`);
+        if (lastErrorLine) {
+            console.log(`${c.warn('[WARN]')} Latest error:   ${lastErrorLine}`);
+        }
+
+        console.log(`\n${c.bright('Machine Readable')}`);
+        console.log(`MODE_REQUESTED=${parsed.options.mode}`);
+        console.log(`MODE_RESOLVED=${mode}`);
+        console.log(`USER_BUS_OK=${userBus.ok}`);
+        console.log(`LINGER=${linger.value}`);
+        console.log(`USER_BACKEND_UNIT_INSTALLED=${userUnitInstalled}`);
+        console.log(`USER_FRONTEND_UNIT_INSTALLED=${userFrontendUnitInstalled}`);
+        console.log(`SYSTEM_BACKEND_UNIT_INSTALLED=${systemUnitInstalled}`);
+        console.log(`SYSTEM_FRONTEND_UNIT_INSTALLED=${systemFrontendUnitInstalled}`);
+        console.log(`USER_BACKEND_ACTIVE=${userState.backend.active}`);
+        console.log(`USER_BACKEND_ENABLED=${userState.backend.enabled}`);
+        console.log(`USER_FRONTEND_ACTIVE=${userState.frontend.active}`);
+        console.log(`USER_FRONTEND_ENABLED=${userState.frontend.enabled}`);
+        console.log(`SYSTEM_BACKEND_ACTIVE=${systemState.backend.active}`);
+        console.log(`SYSTEM_BACKEND_ENABLED=${systemState.backend.enabled}`);
+        console.log(`SYSTEM_FRONTEND_ACTIVE=${systemState.frontend.active}`);
+        console.log(`SYSTEM_FRONTEND_ENABLED=${systemState.frontend.enabled}`);
+        console.log(`BACKEND_PORT=${selectedModePort}`);
+        console.log(`BACKEND_PORT_REACHABLE=${portReachable}`);
+        console.log(`FRONTEND_PORT=${selectedModeFrontendPort}`);
+        console.log(`FRONTEND_PORT_REACHABLE=${frontendPortReachable}`);
+        console.log(`LAST_ERROR_LINE=${JSON.stringify(lastErrorLine || '')}\n`);
+        return;
+    }
+
+    const serviceDefs = [
+        {
+            servicePath,
+        },
+        {
+            servicePath: frontendServicePath,
+        },
+    ];
+
+    switch (parsed.subcommand) {
+        case 'install': {
+            if (parsed.options.mode === 'auto' && mode === 'system' && !userBus.ok) {
+                console.log(`${c.warn('[WARN]')} User mode is unavailable; auto mode is falling back to system mode.`);
+            }
+
+            try {
+                fs.mkdirSync(path.dirname(servicePath), { recursive: true });
+                fs.mkdirSync(path.dirname(frontendServicePath), { recursive: true });
+
+                const backendUnitContent = buildDaemonServiceUnit({
+                    appRoot,
+                    serverPort: portNum,
+                    databasePath,
+                    nodeExecPath: context.nodeExecPath,
+                    cliEntry: context.cliEntry,
+                });
+                fs.writeFileSync(servicePath, backendUnitContent, 'utf8');
+
+                const frontendUnitContent = buildFrontendDaemonServiceUnit({
+                    appRoot,
+                    frontendPort: frontendPortNum,
+                    nodeExecPath: context.nodeExecPath,
+                    cliEntry: context.cliEntry,
+                });
+                fs.writeFileSync(frontendServicePath, frontendUnitContent, 'utf8');
+            } catch (fileError) {
+                if (mode === 'system' && (fileError.code === 'EACCES' || fileError.code === 'EPERM')) {
+                    const installHint = buildDaemonCliCommand(
+                        {
+                            subcommand: 'install',
+                            mode: 'system',
+                            extraArgs: ['--port', String(portNum), '--frontend-port', String(frontendPortNum)],
+                        },
+                        daemonCommandContext
+                    );
+                    throw new Error(
+                        `Permission denied writing daemon unit files (${servicePath}, ${frontendServicePath}). ` +
+                        `Try: ${installHint}`
+                    );
+                }
+                throw fileError;
+            }
+
+            runSystemctl(mode, ['daemon-reload']);
+            runSystemctl(mode, ['enable', '--now', DAEMON_SERVICE_NAME]);
+            runSystemctl(mode, ['enable', '--now', FRONTEND_DAEMON_SERVICE_NAME]);
+
+            if (mode === 'user') {
+                const lingerResult = runCommand('loginctl', ['enable-linger', os.userInfo().username]);
+                if (lingerResult.status !== 0) {
+                    console.log(`${c.warn('[WARN]')} Could not enable linger automatically.`);
+                    console.log(`       ${c.dim(extractCommandError(lingerResult, 'Unknown linger error'))}`);
+                    console.log(`       ${c.tip('[TIP]')} Run with sufficient privileges: ${c.bright(`sudo loginctl enable-linger ${os.userInfo().username}`)}`);
+                }
+            }
+
+            const installedPort = getPortFromServiceUnit(servicePath) || portNum;
+            const installedFrontendPort = getPortFromServiceUnit(frontendServicePath) || frontendPortNum;
+            await healthCheckOrThrow(mode, DAEMON_SERVICE_NAME, installedPort, c);
+            await healthCheckOrThrow(mode, FRONTEND_DAEMON_SERVICE_NAME, installedFrontendPort, c);
+
+            const backendState = getServiceState(mode, DAEMON_SERVICE_NAME);
+            const frontendState = getServiceState(mode, FRONTEND_DAEMON_SERVICE_NAME);
+            console.log(`\n${c.ok('✔')} Daemon installed and started.`);
+            console.log(`   Mode:    ${c.bright(mode)}`);
+            console.log(`   Backend Unit:   ${c.dim(servicePath)}`);
+            console.log(`   Frontend Unit:  ${c.dim(frontendServicePath)}`);
+            console.log(`   Backend Active: ${c.bright(backendState.active)}`);
+            console.log(`   Backend Enabled:${c.bright(backendState.enabled)}`);
+            console.log(`   Frontend Active:${c.bright(frontendState.active)}`);
+            console.log(`   Frontend Enabled:${c.bright(frontendState.enabled)}`);
+            console.log(`   Backend URL:    ${c.bright(`http://localhost:${installedPort}`)}`);
+            console.log(`   Frontend URL:   ${c.bright(`http://localhost:${installedFrontendPort}`)}\n`);
+            if (mode === 'system') {
+                const statusCommand = buildDaemonCliCommand(
+                    { subcommand: 'status', mode: 'system' },
+                    daemonCommandContext
+                );
+                const stopCommand = buildDaemonCliCommand(
+                    { subcommand: 'stop', mode: 'system' },
+                    daemonCommandContext
+                );
+                const logsCommand = buildDaemonCliCommand(
+                    { subcommand: 'logs', mode: 'system' },
+                    daemonCommandContext
+                );
+                console.log(`${c.ok('[OK]')} System daemon is active for backend and frontend.`);
+                console.log(`${c.info('[INFO]')} Backend health: ${c.bright(`http://localhost:${installedPort}/health`)}`);
+                console.log(`${c.info('[INFO]')} Frontend: ${c.bright(`http://localhost:${installedFrontendPort}/`)}`);
+                console.log(`${c.info('[INFO]')} Status: ${c.bright(statusCommand)}`);
+                console.log(`${c.info('[INFO]')} Stop: ${c.bright(stopCommand)}`);
+                console.log(`${c.info('[INFO]')} Logs: ${c.bright(logsCommand)}\n`);
+            } else {
+                const linger = probeLinger();
+                const statusCommand = buildDaemonCliCommand(
+                    { subcommand: 'status', mode: 'user' },
+                    daemonCommandContext
+                );
+                const stopCommand = buildDaemonCliCommand(
+                    { subcommand: 'stop', mode: 'user' },
+                    daemonCommandContext
+                );
+                const logsCommand = buildDaemonCliCommand(
+                    { subcommand: 'logs', mode: 'user' },
+                    daemonCommandContext
+                );
+                console.log(`${c.ok('[OK]')} User daemon is active for backend and frontend.`);
+                console.log(`${c.info('[INFO]')} Backend health: ${c.bright(`http://localhost:${installedPort}/health`)}`);
+                console.log(`${c.info('[INFO]')} Frontend: ${c.bright(`http://localhost:${installedFrontendPort}/`)}`);
+                console.log(`${c.info('[INFO]')} Status: ${c.bright(statusCommand)}`);
+                console.log(`${c.info('[INFO]')} Stop: ${c.bright(stopCommand)}`);
+                console.log(`${c.info('[INFO]')} Logs: ${c.bright(logsCommand)}`);
+                if (linger.value !== 'yes') {
+                    console.log(`${c.tip('[TIP]')} Enable linger for reboot/login persistence: ${c.bright(`sudo loginctl enable-linger ${os.userInfo().username}`)}\n`);
+                } else {
+                    console.log('');
+                }
+            }
+            break;
+        }
+
+        case 'start':
+            runSystemctl(mode, ['start', DAEMON_SERVICE_NAME]);
+            runSystemctl(mode, ['start', FRONTEND_DAEMON_SERVICE_NAME]);
+            await healthCheckOrThrow(mode, DAEMON_SERVICE_NAME, effectivePort, c);
+            await healthCheckOrThrow(mode, FRONTEND_DAEMON_SERVICE_NAME, effectiveFrontendPort, c);
+            console.log(`${c.ok('[OK]')} Backend and frontend services started.`);
+            break;
+
+        case 'stop':
+            runSystemctl(mode, ['stop', FRONTEND_DAEMON_SERVICE_NAME], { allowFailure: true });
+            runSystemctl(mode, ['stop', DAEMON_SERVICE_NAME]);
+            console.log(`${c.ok('[OK]')} Backend and frontend services stopped (auto-start remains enabled).`);
+            break;
+
+        case 'restart':
+            runSystemctl(mode, ['restart', DAEMON_SERVICE_NAME]);
+            runSystemctl(mode, ['restart', FRONTEND_DAEMON_SERVICE_NAME]);
+            await healthCheckOrThrow(mode, DAEMON_SERVICE_NAME, effectivePort, c);
+            await healthCheckOrThrow(mode, FRONTEND_DAEMON_SERVICE_NAME, effectiveFrontendPort, c);
+            console.log(`${c.ok('[OK]')} Backend and frontend services restarted.`);
+            break;
+
+        case 'enable':
+            runSystemctl(mode, ['enable', DAEMON_SERVICE_NAME]);
+            runSystemctl(mode, ['enable', FRONTEND_DAEMON_SERVICE_NAME]);
+            console.log(`${c.ok('[OK]')} Backend and frontend services enabled for auto-start.`);
+            break;
+
+        case 'disable':
+            runSystemctl(mode, ['disable', DAEMON_SERVICE_NAME]);
+            runSystemctl(mode, ['disable', FRONTEND_DAEMON_SERVICE_NAME]);
+            console.log(`${c.ok('[OK]')} Backend and frontend services disabled for auto-start.`);
+            break;
+
+        case 'logs': {
+            const logsResult = readLogs(mode, 100, true, [DAEMON_SERVICE_NAME, FRONTEND_DAEMON_SERVICE_NAME]);
+            if (logsResult.status !== 0) {
+                throw new Error(extractCommandError(logsResult, 'Unable to read daemon logs'));
+            }
+            break;
+        }
+
+        case 'uninstall': {
+            runSystemctl(mode, ['stop', FRONTEND_DAEMON_SERVICE_NAME], { allowFailure: true });
+            runSystemctl(mode, ['disable', FRONTEND_DAEMON_SERVICE_NAME], { allowFailure: true });
+            runSystemctl(mode, ['stop', DAEMON_SERVICE_NAME], { allowFailure: true });
+            runSystemctl(mode, ['disable', DAEMON_SERVICE_NAME], { allowFailure: true });
+
+            for (const def of serviceDefs) {
+                if (!fs.existsSync(def.servicePath)) continue;
+                try {
+                    fs.unlinkSync(def.servicePath);
+                } catch (unlinkError) {
+                    if (mode === 'system' && (unlinkError.code === 'EACCES' || unlinkError.code === 'EPERM')) {
+                        const uninstallHint = buildDaemonCliCommand(
+                            { subcommand: 'uninstall', mode: 'system' },
+                            daemonCommandContext
+                        );
+                        throw new Error(`Permission denied removing ${def.servicePath}. Try: ${uninstallHint}`);
+                    }
+                    throw unlinkError;
+                }
+            }
+            runSystemctl(mode, ['daemon-reload'], { allowFailure: true });
+            console.log(`${c.ok('[OK]')} Backend and frontend daemons uninstalled.`);
+            break;
+        }
+
+        case 'status':
+        default: {
+            const backendState = getServiceState(mode, DAEMON_SERVICE_NAME);
+            const frontendState = getServiceState(mode, FRONTEND_DAEMON_SERVICE_NAME);
+            const backendUnitExists = fs.existsSync(servicePath);
+            const frontendUnitExists = fs.existsSync(frontendServicePath);
+            const selectedPort = getPortFromServiceUnit(servicePath) || portNum;
+            const selectedFrontendPort = getPortFromServiceUnit(frontendServicePath) || frontendPortNum;
+            console.log(`\n${c.bright('Pixcode Daemon Status')}\n`);
+            console.log(`${c.info('[INFO]')} Mode:      ${c.bright(mode)} ${parsed.options.mode === 'auto' ? c.dim('(resolved from auto)') : ''}`);
+            console.log(`${c.info('[INFO]')} Backend Unit:   ${c.dim(servicePath)} ${backendUnitExists ? c.ok('[OK]') : c.warn('[MISSING]')}`);
+            console.log(`${c.info('[INFO]')} Backend Active: ${c.bright(backendState.active)}`);
+            console.log(`${c.info('[INFO]')} Backend Enabled:${c.bright(backendState.enabled)}`);
+            console.log(`${c.info('[INFO]')} Backend Port:   ${c.bright(String(selectedPort))}`);
+            console.log(`${c.info('[INFO]')} Frontend Unit:  ${c.dim(frontendServicePath)} ${frontendUnitExists ? c.ok('[OK]') : c.warn('[MISSING]')}`);
+            console.log(`${c.info('[INFO]')} Frontend Active:${c.bright(frontendState.active)}`);
+            console.log(`${c.info('[INFO]')} Frontend Enabled:${c.bright(frontendState.enabled)}`);
+            console.log(`${c.info('[INFO]')} Frontend Port:  ${c.bright(String(selectedFrontendPort))}`);
+            console.log('');
+        }
+    }
+}