@hienlh/ppm 0.7.31 → 0.7.32

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.7.32] - 2026-03-23
+
+### Added
+- **PPM Cloud CLI**: `ppm cloud login/logout/link/unlink/status/devices` — connect PPM instances to PPM Cloud for device registry + tunnel URL sync
+- **Auto-sync heartbeat**: `ppm start --share` automatically syncs tunnel URL to cloud every 5 minutes if device is linked
+- **Cloud URL config**: `ppm config set cloud_url <url>` to use custom cloud instance
+
+### Security
+- Cloud auth files (`cloud-auth.json`, `cloud-device.json`) restricted to owner-only (chmod 0o600)
+- XSS prevention in OAuth callback HTML
+- Heartbeat interval cleanup prevents duplicate timers on restart
+
 ## [0.7.31] - 2026-03-23
 
 ### Improved

package/package.json

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

package/src/cli/commands/cloud.ts

@@ -0,0 +1,192 @@
+import type { Command } from "commander";
+
+export function registerCloudCommands(program: Command): void {
+  const cmd = program
+    .command("cloud")
+    .description("PPM Cloud — device registry + tunnel URL sync");
+
+  cmd
+    .command("login")
+    .description("Sign in with Google (opens browser)")
+    .option("--url <url>", "Cloud URL override")
+    .action(async (options) => {
+      const {
+        startLoginServer,
+        getCloudAuth,
+        DEFAULT_CLOUD_URL,
+      } = await import("../../services/cloud.service.ts");
+      const { configService } = await import("../../services/config.service.ts");
+
+      const cloudUrl =
+        options.url ||
+        configService.get("cloud_url") ||
+        DEFAULT_CLOUD_URL;
+
+      // Check if already logged in
+      const existing = getCloudAuth();
+      if (existing) {
+        console.log(`  Already logged in as ${existing.email}`);
+        console.log(`  Run 'ppm cloud logout' to switch accounts.\n`);
+        return;
+      }
+
+      try {
+        const auth = await startLoginServer(cloudUrl);
+        console.log(`  ✓  Logged in as ${auth.email}\n`);
+        console.log(`  Next: run 'ppm cloud link' to register this machine.\n`);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Login failed: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("logout")
+    .description("Sign out from PPM Cloud")
+    .action(async () => {
+      const { removeCloudAuth, getCloudAuth } = await import(
+        "../../services/cloud.service.ts"
+      );
+
+      const auth = getCloudAuth();
+      removeCloudAuth();
+      if (auth) {
+        console.log(`  ✓  Logged out (was: ${auth.email})\n`);
+      } else {
+        console.log(`  Not logged in.\n`);
+      }
+    });
+
+  cmd
+    .command("link")
+    .description("Register this machine with PPM Cloud")
+    .option("-n, --name <name>", "Machine display name")
+    .action(async (options) => {
+      const { linkDevice } = await import("../../services/cloud.service.ts");
+
+      try {
+        const device = await linkDevice(options.name);
+        console.log(`  ✓  Machine linked`);
+        console.log(`     Name: ${device.name}`);
+        console.log(`     ID: ${device.device_id}`);
+        console.log(`\n  Run 'ppm start --share' to sync tunnel URL to cloud.\n`);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Link failed: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("unlink")
+    .description("Remove this machine from PPM Cloud")
+    .action(async () => {
+      const { unlinkDevice, getCloudDevice } = await import(
+        "../../services/cloud.service.ts"
+      );
+
+      const device = getCloudDevice();
+      if (!device) {
+        console.log(`  Not linked to cloud.\n`);
+        return;
+      }
+
+      try {
+        await unlinkDevice();
+        console.log(`  ✓  Machine unlinked (was: ${device.name})\n`);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Unlink failed: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("status")
+    .description("Show PPM Cloud connection status")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { getCloudAuth, getCloudDevice } = await import(
+        "../../services/cloud.service.ts"
+      );
+
+      const auth = getCloudAuth();
+      const device = getCloudDevice();
+
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            logged_in: !!auth,
+            email: auth?.email ?? null,
+            cloud_url: auth?.cloud_url ?? null,
+            linked: !!device,
+            device_name: device?.name ?? null,
+            device_id: device?.device_id ?? null,
+          }),
+        );
+        return;
+      }
+
+      console.log(`\n  PPM Cloud status\n`);
+
+      if (auth) {
+        console.log(`  Logged in:  ${auth.email}`);
+        console.log(`  Cloud URL:  ${auth.cloud_url}`);
+      } else {
+        console.log(`  Logged in:  no`);
+        console.log(`  Run 'ppm cloud login' to sign in.`);
+      }
+
+      if (device) {
+        console.log(`  Machine:    ${device.name} (${device.device_id.slice(0, 8)}...)`);
+        console.log(`  Linked at:  ${device.linked_at}`);
+      } else {
+        console.log(`  Machine:    not linked`);
+        if (auth) console.log(`  Run 'ppm cloud link' to register this machine.`);
+      }
+
+      console.log();
+    });
+
+  cmd
+    .command("devices")
+    .description("List all registered devices from cloud")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { listDevices } = await import("../../services/cloud.service.ts");
+
+      try {
+        const devices = await listDevices();
+
+        if (options.json) {
+          console.log(JSON.stringify({ devices }));
+          return;
+        }
+
+        if (devices.length === 0) {
+          console.log(`  No devices registered.\n`);
+          return;
+        }
+
+        console.log(`\n  PPM Cloud devices (${devices.length})\n`);
+        for (const d of devices) {
+          const status = d.computedStatus === "online" ? "● online " : "○ offline";
+          const url = d.tunnelUrl || "(no tunnel)";
+          const lastSeen = d.lastHeartbeat
+            ? new Date(d.lastHeartbeat).toLocaleString()
+            : "never";
+          console.log(`  ${d.name}`);
+          console.log(`    Status:    ${status}`);
+          console.log(`    Tunnel:    ${url}`);
+          console.log(`    Last seen: ${lastSeen}`);
+          console.log(`    Version:   ${d.version || "unknown"}`);
+          console.log();
+        }
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗  Failed: ${msg}\n`);
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -124,4 +124,7 @@ registerChatCommands(program);
 const { registerAutoStartCommands } = await import("./cli/commands/autostart.ts");
 registerAutoStartCommands(program);
 
+const { registerCloudCommands } = await import("./cli/commands/cloud.ts");
+registerCloudCommands(program);
+
 program.parse();

package/src/server/index.ts

@@ -412,6 +412,13 @@ export async function startServer(options: {
       const qr = await import("qrcode-terminal");
       console.log();
       qr.generate(shareUrl, { small: true });
+
+      // Auto-sync tunnel URL to PPM Cloud (if linked)
+      import("../services/cloud.service.ts")
+        .then(({ startHeartbeat, getCloudDevice }) => {
+          if (getCloudDevice()) startHeartbeat(shareUrl);
+        })
+        .catch(() => {});
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`  ✗  Share failed: ${msg}`);
@@ -470,6 +477,13 @@ if (process.argv.includes("__serve__")) {
       const { tunnelService } = await import("../services/tunnel.service.ts");
       tunnelService.setExternalUrl(status.shareUrl);
       if (status.tunnelPid) tunnelService.setExternalPid(status.tunnelPid);
+
+      // Auto-sync tunnel URL to PPM Cloud (daemon mode)
+      import("../services/cloud.service.ts")
+        .then(({ startHeartbeat, getCloudDevice }) => {
+          if (getCloudDevice()) startHeartbeat(status.shareUrl);
+        })
+        .catch(() => {});
     }
   } catch { /* status.json missing or no shareUrl — normal */ }
 

package/src/services/cloud.service.ts

@@ -0,0 +1,345 @@
+import { resolve } from "node:path";
+import { homedir, hostname } from "node:os";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { VERSION } from "../version.ts";
+
+const PPM_DIR = resolve(homedir(), ".ppm");
+const AUTH_FILE = resolve(PPM_DIR, "cloud-auth.json");
+const DEVICE_FILE = resolve(PPM_DIR, "cloud-device.json");
+const MACHINE_ID_FILE = resolve(PPM_DIR, "machine-id");
+
+const DEFAULT_CLOUD_URL = "https://ppm.hienle.tech";
+const HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+// ─── Types ──────────────────────────────────────────────────────────────
+
+interface CloudAuth {
+  access_token: string;
+  refresh_token: string;
+  email: string;
+  cloud_url: string;
+  saved_at: string;
+}
+
+interface CloudDevice {
+  device_id: string;
+  secret_key: string;
+  name: string;
+  machine_id: string;
+  cloud_url: string;
+  linked_at: string;
+}
+
+interface DeviceInfo {
+  id: string;
+  machineId: string;
+  name: string;
+  tunnelUrl: string | null;
+  version: string | null;
+  lastHeartbeat: string | null;
+  computedStatus: string;
+  createdAt: string;
+}
+
+// ─── Machine ID ─────────────────────────────────────────────────────────
+
+/** Get or generate a stable machine ID (random UUID, persists across reboots) */
+export function getMachineId(): string {
+  if (existsSync(MACHINE_ID_FILE)) {
+    return readFileSync(MACHINE_ID_FILE, "utf-8").trim();
+  }
+  const id = randomBytes(16).toString("hex");
+  ensurePpmDir();
+  writeFileSync(MACHINE_ID_FILE, id);
+  return id;
+}
+
+// ─── Auth ───────────────────────────────────────────────────────────────
+
+/** Read saved cloud auth credentials */
+export function getCloudAuth(): CloudAuth | null {
+  try {
+    if (!existsSync(AUTH_FILE)) return null;
+    return JSON.parse(readFileSync(AUTH_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Save cloud auth credentials (restricted permissions) */
+export function saveCloudAuth(auth: CloudAuth): void {
+  ensurePpmDir();
+  writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2));
+  try { chmodSync(AUTH_FILE, 0o600); } catch {}
+}
+
+/** Remove cloud auth credentials */
+export function removeCloudAuth(): void {
+  try { if (existsSync(AUTH_FILE)) unlinkSync(AUTH_FILE); } catch {}
+}
+
+// ─── Device ─────────────────────────────────────────────────────────────
+
+/** Read saved cloud device info */
+export function getCloudDevice(): CloudDevice | null {
+  try {
+    if (!existsSync(DEVICE_FILE)) return null;
+    return JSON.parse(readFileSync(DEVICE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Save cloud device info (restricted permissions) */
+export function saveCloudDevice(device: CloudDevice): void {
+  ensurePpmDir();
+  writeFileSync(DEVICE_FILE, JSON.stringify(device, null, 2));
+  try { chmodSync(DEVICE_FILE, 0o600); } catch {}
+}
+
+/** Remove cloud device info */
+export function removeCloudDevice(): void {
+  try { if (existsSync(DEVICE_FILE)) unlinkSync(DEVICE_FILE); } catch {}
+}
+
+// ─── API Client ─────────────────────────────────────────────────────────
+
+/** Make authenticated request to cloud API */
+async function cloudFetch(
+  path: string,
+  options: RequestInit = {},
+  auth?: CloudAuth,
+): Promise<Response> {
+  const creds = auth || getCloudAuth();
+  if (!creds) throw new Error("Not logged in. Run 'ppm cloud login' first.");
+
+  const url = `${creds.cloud_url}${path}`;
+  const headers = new Headers(options.headers);
+  headers.set("Authorization", `Bearer ${creds.access_token}`);
+  headers.set("Content-Type", "application/json");
+
+  let res = await fetch(url, { ...options, headers });
+
+  // Auto-refresh if 401
+  if (res.status === 401 && creds.refresh_token) {
+    const refreshed = await refreshAccessToken(creds);
+    if (refreshed) {
+      headers.set("Authorization", `Bearer ${refreshed.access_token}`);
+      res = await fetch(url, { ...options, headers });
+    }
+  }
+
+  return res;
+}
+
+/** Refresh access token — forces re-login for now (refresh endpoint uses cookies, not CLI-friendly) */
+async function refreshAccessToken(_auth: CloudAuth): Promise<CloudAuth | null> {
+  // TODO: extend cloud API /auth/refresh to return tokens in response body for CLI
+  return null;
+}
+
+// ─── CLI Login ──────────────────────────────────────────────────────────
+
+/**
+ * Start a temporary localhost server to catch the OAuth callback.
+ * Returns the auth credentials after successful login.
+ */
+export async function startLoginServer(cloudUrl: string): Promise<CloudAuth> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.stop();
+      reject(new Error("Login timed out after 120 seconds"));
+    }, 120_000);
+
+    const server = Bun.serve({
+      port: 0, // random available port
+      fetch(req) {
+        const url = new URL(req.url);
+        if (url.pathname === "/callback") {
+          const accessToken = url.searchParams.get("access_token");
+          const refreshToken = url.searchParams.get("refresh_token");
+          const email = url.searchParams.get("email");
+
+          if (!accessToken || !email) {
+            clearTimeout(timeout);
+            server.stop();
+            reject(new Error("OAuth callback missing required parameters"));
+            return new Response(errorHtml("Login failed — missing parameters"), {
+              headers: { "Content-Type": "text/html" },
+            });
+          }
+
+          const auth: CloudAuth = {
+            access_token: accessToken,
+            refresh_token: refreshToken || "",
+            email,
+            cloud_url: cloudUrl,
+            saved_at: new Date().toISOString(),
+          };
+
+          saveCloudAuth(auth);
+          clearTimeout(timeout);
+          // Delay stop to allow response to be sent
+          setTimeout(() => server.stop(), 500);
+          resolve(auth);
+
+          return new Response(successHtml(email), {
+            headers: { "Content-Type": "text/html" },
+          });
+        }
+        return new Response("Not found", { status: 404 });
+      },
+    });
+
+    // Open browser with cli_port param
+    const loginUrl = `${cloudUrl}/auth/google/login?cli_port=${server.port}`;
+    openBrowser(loginUrl);
+    console.log(`\n  Waiting for Google login...`);
+    console.log(`  If browser didn't open, visit: ${loginUrl}\n`);
+  });
+}
+
+// ─── Device Registration ────────────────────────────────────────────────
+
+/** Register or re-register this machine with cloud */
+export async function linkDevice(name?: string): Promise<CloudDevice> {
+  const auth = getCloudAuth();
+  if (!auth) throw new Error("Not logged in. Run 'ppm cloud login' first.");
+
+  const machineId = getMachineId();
+  const deviceName = name || hostname() || "Unknown Machine";
+
+  const res = await cloudFetch("/api/devices", {
+    method: "POST",
+    body: JSON.stringify({
+      machine_id: machineId,
+      name: deviceName,
+      version: VERSION,
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Failed to register device: ${err}`);
+  }
+
+  const data = await res.json() as { id: string; secret_key: string };
+
+  const device: CloudDevice = {
+    device_id: data.id,
+    secret_key: data.secret_key,
+    name: deviceName,
+    machine_id: machineId,
+    cloud_url: auth.cloud_url,
+    linked_at: new Date().toISOString(),
+  };
+
+  saveCloudDevice(device);
+  return device;
+}
+
+/** Unlink this machine from cloud */
+export async function unlinkDevice(): Promise<void> {
+  const device = getCloudDevice();
+  if (!device) {
+    removeCloudDevice();
+    return;
+  }
+
+  try {
+    await cloudFetch(`/api/devices/${device.device_id}`, { method: "DELETE" });
+  } catch {
+    // Continue even if cloud unreachable — clean up local state
+  }
+  removeCloudDevice();
+}
+
+/** List all devices for the logged-in user */
+export async function listDevices(): Promise<DeviceInfo[]> {
+  const res = await cloudFetch("/api/devices");
+  if (!res.ok) throw new Error(`Failed to list devices: ${res.status}`);
+  const data = await res.json() as { devices: DeviceInfo[] };
+  return data.devices;
+}
+
+// ─── Heartbeat ──────────────────────────────────────────────────────────
+
+/** Send a single heartbeat to cloud (non-blocking, logs errors) */
+export async function sendHeartbeat(tunnelUrl: string): Promise<boolean> {
+  const device = getCloudDevice();
+  if (!device) return false;
+
+  try {
+    const res = await fetch(`${device.cloud_url}/api/devices/${device.device_id}/heartbeat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        secret_key: device.secret_key,
+        tunnel_url: tunnelUrl,
+        status: "online",
+      }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Start periodic heartbeat (call once after tunnel URL is obtained) */
+export function startHeartbeat(tunnelUrl: string): void {
+  // Clear any existing heartbeat to prevent duplicates on restart
+  if (heartbeatTimer) clearInterval(heartbeatTimer);
+
+  // Initial heartbeat immediately
+  sendHeartbeat(tunnelUrl).then((ok) => {
+    if (ok) console.log("  ➜  Cloud:   synced to PPM Cloud");
+    else console.warn("  ⚠  Cloud sync failed (non-blocking)");
+  });
+
+  // Periodic heartbeat every 5 minutes
+  heartbeatTimer = setInterval(() => {
+    sendHeartbeat(tunnelUrl).catch(() => {});
+  }, HEARTBEAT_INTERVAL_MS);
+}
+
+/** Stop periodic heartbeat */
+export function stopHeartbeat(): void {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function ensurePpmDir(): void {
+  if (!existsSync(PPM_DIR)) mkdirSync(PPM_DIR, { recursive: true });
+}
+
+function openBrowser(url: string): void {
+  try {
+    if (process.platform === "darwin") {
+      Bun.spawn(["open", url], { stdout: "ignore", stderr: "ignore" });
+    } else if (process.platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", url], { stdout: "ignore", stderr: "ignore" });
+    } else {
+      Bun.spawn(["xdg-open", url], { stdout: "ignore", stderr: "ignore" });
+    }
+  } catch {}
+}
+
+function successHtml(email: string): string {
+  const safe = email.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  return `<!DOCTYPE html><html><body style="font-family:system-ui;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0a0a0a;color:#fff">
+<div style="text-align:center"><h1>✓ Logged in</h1><p>Logged in as <b>${safe}</b></p><p style="color:#888">You can close this tab and return to the terminal.</p></div></body></html>`;
+}
+
+function errorHtml(message: string): string {
+  return `<!DOCTYPE html><html><body style="font-family:system-ui;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0a0a0a;color:#fff">
+<div style="text-align:center"><h1>✗ Login Failed</h1><p>${message}</p></div></body></html>`;
+}
+
+export { DEFAULT_CLOUD_URL, HEARTBEAT_INTERVAL_MS };

package/src/types/config.ts

@@ -21,6 +21,7 @@ export interface PpmConfig {
   ai: AIConfig;
   push?: PushConfig;
   telegram?: TelegramConfig;
+  cloud_url?: string;
 }
 
 export interface AuthConfig {