@hienlh/ppm 0.7.28 → 0.7.29

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.7.29] - 2026-03-22
+
+### Added
+- **Auto-start on boot**: `ppm autostart enable/disable/status` registers PPM to start automatically via OS-native mechanisms — macOS launchd, Linux systemd, Windows Registry Run key
+- **Cross-platform support**: auto-detects compiled binary vs bun runtime, resolves paths correctly on all platforms
+- **VBScript hidden wrapper**: Windows auto-start runs PPM without visible console window
+- **GitHub Actions CI**: test matrix for macOS, Linux, and Windows with unit + integration tests
+
+### Technical
+- 2-layer architecture: generator (pure functions, testable) + register (OS interaction)
+- 40 unit tests + 20 integration tests (platform-specific with `describe.if`)
+- KeepAlive/Restart-on-failure for crash recovery on all platforms
+
 ## [0.7.28] - 2026-03-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.7.28",
+  "version": "0.7.29",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/cli/commands/autostart.ts

@@ -0,0 +1,94 @@
+import type { Command } from "commander";
+import { configService } from "../../services/config.service.ts";
+
+export function registerAutoStartCommands(program: Command): void {
+  const cmd = program
+    .command("autostart")
+    .description("Manage auto-start on boot (enable/disable/status)");
+
+  cmd
+    .command("enable")
+    .description("Register PPM to start automatically on boot")
+    .option("-p, --port <port>", "Override port")
+    .option("-s, --share", "Enable Cloudflare tunnel on boot")
+    .option("-c, --config <path>", "Config file path")
+    .option("--profile <name>", "DB profile name")
+    .action(async (options) => {
+      const { enableAutoStart } = await import("../../services/autostart-register.ts");
+
+      configService.load(options.config);
+      const port = parseInt(options.port ?? String(configService.get("port")), 10);
+      const host = configService.get("host") ?? "0.0.0.0";
+
+      const config = {
+        port,
+        host,
+        share: !!options.share,
+        configPath: options.config,
+        profile: options.profile,
+      };
+
+      try {
+        console.log("  Registering auto-start...\n");
+        const servicePath = await enableAutoStart(config);
+        console.log(`  ✓  Auto-start enabled`);
+        console.log(`     Service: ${servicePath}`);
+        console.log(`     Port: ${port}`);
+        if (options.share) console.log(`     Tunnel: enabled`);
+        console.log(`\n  PPM will start automatically on boot.`);
+
+        if (process.platform === "darwin") {
+          console.log(`\n  Note: On macOS Ventura+, you may need to allow PPM in`);
+          console.log(`  System Settings > General > Login Items.`);
+        }
+        if (process.platform === "linux") {
+          console.log(`\n  Note: 'loginctl enable-linger' was called to allow`);
+          console.log(`  boot-time start without login.`);
+        }
+        console.log();
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Failed to enable auto-start: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("disable")
+    .description("Remove PPM auto-start registration")
+    .action(async () => {
+      const { disableAutoStart } = await import("../../services/autostart-register.ts");
+
+      try {
+        await disableAutoStart();
+        console.log("  ✓  Auto-start disabled. PPM will no longer start on boot.\n");
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Failed to disable auto-start: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("status")
+    .description("Show auto-start status")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { getAutoStartStatus } = await import("../../services/autostart-register.ts");
+
+      const status = getAutoStartStatus();
+
+      if (options.json) {
+        console.log(JSON.stringify(status));
+        return;
+      }
+
+      console.log(`\n  Auto-start status\n`);
+      console.log(`  Platform:  ${status.platform}`);
+      console.log(`  Enabled:   ${status.enabled ? "yes" : "no"}`);
+      console.log(`  Running:   ${status.running ? "yes" : "no"}`);
+      if (status.servicePath) console.log(`  Service:   ${status.servicePath}`);
+      console.log(`  Details:   ${status.details}`);
+      console.log();
+    });
+}

package/src/index.ts

@@ -121,4 +121,7 @@ registerGitCommands(program);
 const { registerChatCommands } = await import("./cli/commands/chat-cmd.ts");
 registerChatCommands(program);
 
+const { registerAutoStartCommands } = await import("./cli/commands/autostart.ts");
+registerAutoStartCommands(program);
+
 program.parse();

package/src/services/autostart-generator.ts

@@ -0,0 +1,213 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export interface AutoStartConfig {
+  port: number;
+  host: string;
+  share: boolean;
+  configPath?: string;
+  profile?: string;
+}
+
+/** Detect whether running from compiled binary or bun runtime */
+export function isCompiledBinary(): boolean {
+  // Compiled Bun binaries don't have "bun" in execPath
+  return !process.execPath.includes("bun");
+}
+
+/** Resolve the absolute path to the bun binary */
+export function resolveBunPath(): string {
+  // 1. Current process is bun itself
+  if (process.execPath.includes("bun")) return process.execPath;
+
+  // 2. Check ~/.bun/bin/bun
+  const home = homedir();
+  const bunHome = resolve(home, ".bun", "bin", "bun");
+  try {
+    const { existsSync } = require("node:fs") as typeof import("node:fs");
+    if (existsSync(bunHome)) return bunHome;
+  } catch {}
+
+  // 3. Check PATH via which/where
+  try {
+    const cmd = process.platform === "win32" ? ["where", "bun"] : ["which", "bun"];
+    const result = Bun.spawnSync({ cmd, stdout: "pipe", stderr: "ignore" });
+    const path = result.stdout.toString().trim().split("\n")[0];
+    if (path) return path;
+  } catch {}
+
+  throw new Error("Could not resolve bun binary. Install Bun or add it to PATH.");
+}
+
+/** Build the command array for the PPM server process */
+export function buildExecCommand(config: AutoStartConfig): string[] {
+  if (isCompiledBinary()) {
+    // Compiled binary: just run self with __serve__ args
+    const args = [process.execPath, "__serve__", String(config.port), config.host];
+    if (config.configPath) args.push(config.configPath);
+    if (config.profile) args.push(config.profile);
+    return args;
+  }
+
+  // Bun runtime: bun run <script> __serve__ <port> <host> [config] [profile]
+  const bunPath = resolveBunPath();
+  const scriptPath = resolve(import.meta.dir, "..", "server", "index.ts");
+  const args = [bunPath, "run", scriptPath, "__serve__", String(config.port), config.host];
+  if (config.configPath) args.push(config.configPath);
+  else args.push(""); // placeholder
+  if (config.profile) args.push(config.profile);
+  else args.push(""); // placeholder
+  return args;
+}
+
+// ─── macOS launchd plist ────────────────────────────────────────────────
+
+const PLIST_LABEL = "com.hienlh.ppm";
+
+export function getPlistPath(): string {
+  return resolve(homedir(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`);
+}
+
+/** Generate macOS launchd plist XML content */
+export function generatePlist(config: AutoStartConfig): string {
+  const cmd = buildExecCommand(config);
+  const logPath = resolve(homedir(), ".ppm", "ppm-launchd.log");
+
+  const programArgs = cmd
+    .map((arg) => `        <string>${escapeXml(arg)}</string>`)
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+${programArgs}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${escapeXml(logPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(logPath)}</string>
+    <key>WorkingDirectory</key>
+    <string>${escapeXml(resolve(homedir(), ".ppm"))}</string>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>
+`;
+}
+
+// ─── Linux systemd service ──────────────────────────────────────────────
+
+export function getServicePath(): string {
+  return resolve(homedir(), ".config", "systemd", "user", "ppm.service");
+}
+
+/** Generate Linux systemd user service file content */
+export function generateSystemdService(config: AutoStartConfig): string {
+  const cmd = buildExecCommand(config);
+  const execStart = cmd.map(shellEscape).join(" ");
+  const bunDir = isCompiledBinary() ? "" : resolve(resolveBunPath(), "..");
+
+  // Build PATH with bun directory prepended
+  const envPath = bunDir
+    ? `Environment="PATH=${bunDir}:/usr/local/bin:/usr/bin:/bin"`
+    : "";
+
+  return `[Unit]
+Description=PPM - Personal Project Manager
+Documentation=https://github.com/hienlh/ppm
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=5
+${envPath}
+WorkingDirectory=${homedir()}/.ppm
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+// ─── Windows Registry Run key ───────────────────────────────────────────
+// Uses HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run — no admin needed
+
+const TASK_NAME = "PPM";
+const WIN_REG_KEY = "HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run";
+
+/** Generate Windows VBScript wrapper content to run PPM hidden */
+export function generateVbsWrapper(config: AutoStartConfig): string {
+  const cmd = buildExecCommand(config);
+  const exe = cmd[0]!;
+  const args = cmd.slice(1).join(" ");
+  return `Set objShell = CreateObject("WScript.Shell")
+objShell.Run """${exe.replace(/\\/g, "\\\\")}""` +
+    ` ${args.replace(/"/g, '""')}", 0, False
+`;
+}
+
+export function getVbsPath(): string {
+  return resolve(homedir(), ".ppm", "run-ppm.vbs");
+}
+
+/** Build reg command to add PPM to Windows startup (no admin) */
+export function buildRegAddCommand(vbsPath: string): string[] {
+  return [
+    "reg", "add", WIN_REG_KEY,
+    "/v", TASK_NAME,
+    "/t", "REG_SZ",
+    "/d", `cscript.exe "${vbsPath}"`,
+    "/f",
+  ];
+}
+
+/** Build reg command to remove PPM from Windows startup */
+export function buildRegDeleteCommand(): string[] {
+  return [
+    "reg", "delete", WIN_REG_KEY,
+    "/v", TASK_NAME,
+    "/f",
+  ];
+}
+
+/** Build reg command to query PPM startup entry */
+export function buildRegQueryCommand(): string[] {
+  return [
+    "reg", "query", WIN_REG_KEY,
+    "/v", TASK_NAME,
+  ];
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+/** Escape special XML characters */
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** Escape a string for shell usage (wrap in quotes if contains spaces) */
+function shellEscape(s: string): string {
+  if (/["\s]/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s;
+}
+
+export { PLIST_LABEL, TASK_NAME };

package/src/services/autostart-register.ts

@@ -0,0 +1,348 @@
+import { existsSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import {
+  type AutoStartConfig,
+  PLIST_LABEL,
+  TASK_NAME,
+  generatePlist,
+  getPlistPath,
+  generateSystemdService,
+  getServicePath,
+  generateVbsWrapper,
+  getVbsPath,
+  buildRegAddCommand,
+  buildRegDeleteCommand,
+  buildRegQueryCommand,
+} from "./autostart-generator.ts";
+
+export interface AutoStartStatus {
+  enabled: boolean;
+  running: boolean;
+  platform: string;
+  servicePath: string | null;
+  details: string;
+}
+
+const METADATA_FILE = resolve(homedir(), ".ppm", "autostart.json");
+
+interface AutoStartMetadata {
+  enabled: boolean;
+  platform: string;
+  servicePath: string;
+  createdAt: string;
+  config: AutoStartConfig;
+}
+
+/** Save autostart metadata to ~/.ppm/autostart.json */
+function saveMetadata(meta: AutoStartMetadata): void {
+  const dir = dirname(METADATA_FILE);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(METADATA_FILE, JSON.stringify(meta, null, 2));
+}
+
+/** Load autostart metadata */
+function loadMetadata(): AutoStartMetadata | null {
+  try {
+    if (!existsSync(METADATA_FILE)) return null;
+    return JSON.parse(readFileSync(METADATA_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Remove autostart metadata file */
+function removeMetadata(): void {
+  try {
+    if (existsSync(METADATA_FILE)) unlinkSync(METADATA_FILE);
+  } catch {}
+}
+
+// ─── macOS ──────────────────────────────────────────────────────────────
+
+async function enableMacOS(config: AutoStartConfig): Promise<string> {
+  const plistPath = getPlistPath();
+  const plistDir = dirname(plistPath);
+
+  if (!existsSync(plistDir)) mkdirSync(plistDir, { recursive: true });
+  writeFileSync(plistPath, generatePlist(config));
+
+  // Unload first if already loaded (ignore errors)
+  Bun.spawnSync({
+    cmd: ["launchctl", "bootout", `gui/${process.getuid!()}`, plistPath],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  // Load the agent
+  const result = Bun.spawnSync({
+    cmd: ["launchctl", "bootstrap", `gui/${process.getuid!()}`, plistPath],
+    stdout: "pipe", stderr: "pipe",
+  });
+
+  if (result.exitCode !== 0) {
+    // Fallback to legacy syntax
+    const legacy = Bun.spawnSync({
+      cmd: ["launchctl", "load", plistPath],
+      stdout: "pipe", stderr: "pipe",
+    });
+    if (legacy.exitCode !== 0) {
+      const err = legacy.stderr.toString().trim();
+      throw new Error(`launchctl load failed: ${err}`);
+    }
+  }
+
+  saveMetadata({
+    enabled: true,
+    platform: "darwin",
+    servicePath: plistPath,
+    createdAt: new Date().toISOString(),
+    config,
+  });
+
+  return plistPath;
+}
+
+async function disableMacOS(): Promise<void> {
+  const plistPath = getPlistPath();
+
+  // Unload
+  Bun.spawnSync({
+    cmd: ["launchctl", "bootout", `gui/${process.getuid!()}`, plistPath],
+    stdout: "ignore", stderr: "ignore",
+  });
+  // Legacy fallback
+  Bun.spawnSync({
+    cmd: ["launchctl", "unload", plistPath],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  // Remove plist file
+  try { if (existsSync(plistPath)) unlinkSync(plistPath); } catch {}
+  removeMetadata();
+}
+
+function statusMacOS(): AutoStartStatus {
+  const plistPath = getPlistPath();
+  const fileExists = existsSync(plistPath);
+
+  // Check if loaded
+  const result = Bun.spawnSync({
+    cmd: ["launchctl", "list"],
+    stdout: "pipe", stderr: "ignore",
+  });
+  const output = result.stdout.toString();
+  const isLoaded = output.includes(PLIST_LABEL);
+
+  return {
+    enabled: fileExists && isLoaded,
+    running: isLoaded,
+    platform: "darwin (launchd)",
+    servicePath: fileExists ? plistPath : null,
+    details: fileExists
+      ? isLoaded ? "Loaded and enabled" : "Plist exists but not loaded"
+      : "Not configured",
+  };
+}
+
+// ─── Linux ──────────────────────────────────────────────────────────────
+
+async function enableLinux(config: AutoStartConfig): Promise<string> {
+  const servicePath = getServicePath();
+  const serviceDir = dirname(servicePath);
+
+  if (!existsSync(serviceDir)) mkdirSync(serviceDir, { recursive: true });
+  writeFileSync(servicePath, generateSystemdService(config));
+
+  // Reload daemon
+  const reload = Bun.spawnSync({
+    cmd: ["systemctl", "--user", "daemon-reload"],
+    stdout: "ignore", stderr: "pipe",
+  });
+  if (reload.exitCode !== 0) {
+    throw new Error(`systemctl daemon-reload failed: ${reload.stderr.toString().trim()}`);
+  }
+
+  // Enable
+  const enable = Bun.spawnSync({
+    cmd: ["systemctl", "--user", "enable", "ppm.service"],
+    stdout: "pipe", stderr: "pipe",
+  });
+  if (enable.exitCode !== 0) {
+    throw new Error(`systemctl enable failed: ${enable.stderr.toString().trim()}`);
+  }
+
+  // Start
+  Bun.spawnSync({
+    cmd: ["systemctl", "--user", "start", "ppm.service"],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  // Enable lingering so service runs at boot without login
+  Bun.spawnSync({
+    cmd: ["loginctl", "enable-linger", process.env.USER || ""],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  saveMetadata({
+    enabled: true,
+    platform: "linux",
+    servicePath,
+    createdAt: new Date().toISOString(),
+    config,
+  });
+
+  return servicePath;
+}
+
+async function disableLinux(): Promise<void> {
+  // Stop + disable
+  Bun.spawnSync({
+    cmd: ["systemctl", "--user", "stop", "ppm.service"],
+    stdout: "ignore", stderr: "ignore",
+  });
+  Bun.spawnSync({
+    cmd: ["systemctl", "--user", "disable", "ppm.service"],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  // Remove service file
+  const servicePath = getServicePath();
+  try { if (existsSync(servicePath)) unlinkSync(servicePath); } catch {}
+
+  // Reload
+  Bun.spawnSync({
+    cmd: ["systemctl", "--user", "daemon-reload"],
+    stdout: "ignore", stderr: "ignore",
+  });
+
+  removeMetadata();
+}
+
+function statusLinux(): AutoStartStatus {
+  const servicePath = getServicePath();
+  const fileExists = existsSync(servicePath);
+
+  // Check enabled
+  const enabled = Bun.spawnSync({
+    cmd: ["systemctl", "--user", "is-enabled", "ppm.service"],
+    stdout: "pipe", stderr: "ignore",
+  });
+  const isEnabled = enabled.stdout.toString().trim() === "enabled";
+
+  // Check active
+  const active = Bun.spawnSync({
+    cmd: ["systemctl", "--user", "is-active", "ppm.service"],
+    stdout: "pipe", stderr: "ignore",
+  });
+  const isActive = active.stdout.toString().trim() === "active";
+
+  return {
+    enabled: isEnabled,
+    running: isActive,
+    platform: "linux (systemd)",
+    servicePath: fileExists ? servicePath : null,
+    details: !fileExists
+      ? "Not configured"
+      : isEnabled && isActive ? "Enabled and running"
+      : isEnabled ? "Enabled but not running"
+      : "Service file exists but not enabled",
+  };
+}
+
+// ─── Windows ────────────────────────────────────────────────────────────
+
+async function enableWindows(config: AutoStartConfig): Promise<string> {
+  const vbsPath = getVbsPath();
+  const vbsDir = dirname(vbsPath);
+
+  if (!existsSync(vbsDir)) mkdirSync(vbsDir, { recursive: true });
+  writeFileSync(vbsPath, generateVbsWrapper(config));
+
+  // Add to HKCU Run key (no admin required)
+  const cmd = buildRegAddCommand(vbsPath);
+  const result = Bun.spawnSync({ cmd, stdout: "pipe", stderr: "pipe" });
+
+  if (result.exitCode !== 0) {
+    const err = result.stderr.toString().trim();
+    throw new Error(`Registry add failed: ${err}`);
+  }
+
+  saveMetadata({
+    enabled: true,
+    platform: "win32",
+    servicePath: vbsPath,
+    createdAt: new Date().toISOString(),
+    config,
+  });
+
+  return vbsPath;
+}
+
+async function disableWindows(): Promise<void> {
+  // Remove from registry
+  const cmd = buildRegDeleteCommand();
+  Bun.spawnSync({ cmd, stdout: "ignore", stderr: "ignore" });
+
+  // Remove VBS wrapper
+  const vbsPath = getVbsPath();
+  try { if (existsSync(vbsPath)) unlinkSync(vbsPath); } catch {}
+
+  removeMetadata();
+}
+
+function statusWindows(): AutoStartStatus {
+  const vbsPath = getVbsPath();
+  const fileExists = existsSync(vbsPath);
+
+  // Check if registry entry exists
+  const cmd = buildRegQueryCommand();
+  const result = Bun.spawnSync({ cmd, stdout: "pipe", stderr: "ignore" });
+  const regExists = result.exitCode === 0 && result.stdout.toString().includes(TASK_NAME);
+
+  return {
+    enabled: regExists,
+    running: false, // Can't detect running state from registry
+    platform: "windows (Registry Run)",
+    servicePath: fileExists ? vbsPath : null,
+    details: regExists
+      ? "Registered (will run at next logon)"
+      : "Not configured",
+  };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/** Enable auto-start for the current platform */
+export async function enableAutoStart(config: AutoStartConfig): Promise<string> {
+  const platform = process.platform;
+  if (platform === "darwin") return enableMacOS(config);
+  if (platform === "linux") return enableLinux(config);
+  if (platform === "win32") return enableWindows(config);
+  throw new Error(`Auto-start not supported on ${platform}`);
+}
+
+/** Disable auto-start for the current platform */
+export async function disableAutoStart(): Promise<void> {
+  const platform = process.platform;
+  if (platform === "darwin") return disableMacOS();
+  if (platform === "linux") return disableLinux();
+  if (platform === "win32") return disableWindows();
+  throw new Error(`Auto-start not supported on ${platform}`);
+}
+
+/** Get auto-start status for the current platform */
+export function getAutoStartStatus(): AutoStartStatus {
+  const platform = process.platform;
+  if (platform === "darwin") return statusMacOS();
+  if (platform === "linux") return statusLinux();
+  if (platform === "win32") return statusWindows();
+  return {
+    enabled: false,
+    running: false,
+    platform: `${platform} (unsupported)`,
+    servicePath: null,
+    details: `Auto-start not supported on ${platform}`,
+  };
+}
+
+export { loadMetadata, METADATA_FILE };