@hienlh/ppm 0.12.12 → 0.13.2

package/src/index.ts

@@ -3,156 +3,170 @@
 import { Command } from "commander";
 import { VERSION } from "./version.ts";
 
-const program = new Command();
-
-program
-  .name("ppm")
-  .description("Personal Project Manager — mobile-first web IDE")
-  .version(VERSION)
-  .hook("preAction", () => {
-    console.log(`  PPM v${VERSION}\n`);
-  });
-
-program
-  .command("start")
-  .description("Start the PPM server (background by default)")
-  .option("-p, --port <port>", "Port to listen on")
-  .option("-s, --share", "(deprecated) Tunnel is now always enabled")
-  .option("--profile <name>", "DB profile name (e.g. 'dev' → ppm.dev.db)")
-  .action(async (options) => {
-    // Set DB profile before any DB access
-    const { setDbProfile } = await import("./services/db.service.ts");
-    if (options.profile) {
-      setDbProfile(options.profile);
-    }
-    // Auto-init on first run
-    const { hasConfig, initProject } = await import("./cli/commands/init.ts");
-    if (!hasConfig()) {
-      await initProject();
-    }
-    const { startServer } = await import("./server/index.ts");
-    await startServer(options);
-  });
-
-program
-  .command("stop")
-  .description("Stop the PPM server (supervisor stays alive)")
-  .option("-a, --all", "Kill all PPM and cloudflared processes (including untracked)")
-  .option("--kill", "Full shutdown (kills supervisor too)")
-  .action(async (options) => {
-    const { stopServer } = await import("./cli/commands/stop.ts");
-    await stopServer(options);
-  });
-
-program
-  .command("down")
-  .description("Fully shut down PPM (supervisor + server + tunnel)")
-  .action(async () => {
-    const { stopServer } = await import("./cli/commands/stop.ts");
-    await stopServer({ kill: true });
-  });
-
-program
-  .command("restart")
-  .description("Restart the server (keeps tunnel alive)")
-  .option("--force", "Force resume from paused state")
-  .action(async (options) => {
-    const { restartServer } = await import("./cli/commands/restart.ts");
-    await restartServer(options);
-  });
-
-program
-  .command("status")
-  .description("Show PPM daemon status")
-  .option("-a, --all", "Show all PPM and cloudflared processes (including untracked)")
-  .option("--json", "Output as JSON")
-  .action(async (options) => {
-    const { showStatus } = await import("./cli/commands/status.ts");
-    await showStatus(options);
-  });
-
-program
-  .command("open")
-  .description("Open PPM in browser")
-  .action(async () => {
-    const { openBrowser } = await import("./cli/commands/open.ts");
-    await openBrowser();
-  });
-
-program
-  .command("logs")
-  .description("View PPM daemon logs")
-  .option("-n, --tail <lines>", "Number of lines to show", "50")
-  .option("-f, --follow", "Follow log output")
-  .option("--clear", "Clear log file")
-  .action(async (options) => {
-    const { showLogs } = await import("./cli/commands/logs.ts");
-    await showLogs(options);
-  });
-
-program
-  .command("report")
-  .description("Report a bug on GitHub (pre-fills env info + logs)")
-  .action(async () => {
-    const { reportBug } = await import("./cli/commands/report.ts");
-    await reportBug();
-  });
-
-program
-  .command("init")
-  .description("Initialize PPM configuration (interactive or via flags)")
-  .option("-p, --port <port>", "Port to listen on")
-  .option("--scan <path>", "Directory to scan for git repos")
-  .option("--auth", "Enable authentication")
-  .option("--no-auth", "Disable authentication")
-  .option("--password <pw>", "Set access password")
-  .option("--share", "Pre-install cloudflared for sharing")
-  .option("-y, --yes", "Non-interactive mode (use defaults + flags)")
-  .action(async (options) => {
-    const { initProject } = await import("./cli/commands/init.ts");
-    await initProject(options);
-  });
-
-const { registerProjectsCommands } = await import("./cli/commands/projects.ts");
-registerProjectsCommands(program);
-
-const { registerConfigCommands } = await import("./cli/commands/config-cmd.ts");
-registerConfigCommands(program);
-
-const { registerGitCommands } = await import("./cli/commands/git-cmd.ts");
-registerGitCommands(program);
-
-const { registerChatCommands } = await import("./cli/commands/chat-cmd.ts");
-registerChatCommands(program);
-
-program
-  .command("upgrade")
-  .description("Check for and install PPM updates")
-  .option("--check", "Only check for updates, don't install")
-  .action(async (options) => {
-    const { upgradeCmd } = await import("./cli/commands/upgrade.ts");
-    await upgradeCmd(options);
-  });
-
-const { registerAutoStartCommands } = await import("./cli/commands/autostart.ts");
-registerAutoStartCommands(program);
-
-const { registerCloudCommands } = await import("./cli/commands/cloud.ts");
-registerCloudCommands(program);
-
-const { registerSkillsCommands } = await import("./cli/commands/skills-cmd.ts");
-registerSkillsCommands(program);
-
-const { registerExtCommands } = await import("./cli/commands/ext-cmd.ts");
-registerExtCommands(program);
-
-const { registerDbCommands } = await import("./cli/commands/db-cmd.ts");
-registerDbCommands(program);
-
-const { registerBotCommands } = await import("./cli/commands/bot-cmd.ts");
-registerBotCommands(program);
-
-const { registerJiraCommands } = await import("./cli/commands/jira-cmd.ts");
-await registerJiraCommands(program);
-
-program.parse();
+/**
+ * Assemble the CLI program without parsing argv. Exported so build-time tools
+ * (e.g. scripts/generate-ppm-skill.ts) can introspect the Commander tree for
+ * auto-generated documentation. `preAction` hooks and action callbacks are
+ * registered but not invoked until `.parseAsync()` runs.
+ */
+export async function buildProgram(): Promise<Command> {
+  const program = new Command();
+
+  program
+    .name("ppm")
+    .description("Personal Project Manager — mobile-first web IDE")
+    .version(VERSION)
+    .hook("preAction", () => {
+      console.log(`  PPM v${VERSION}\n`);
+    });
+
+  program
+    .command("start")
+    .description("Start the PPM server (background by default)")
+    .option("-p, --port <port>", "Port to listen on")
+    .option("-s, --share", "(deprecated) Tunnel is now always enabled")
+    .option("--profile <name>", "DB profile name (e.g. 'dev' → ppm.dev.db)")
+    .action(async (options) => {
+      const { setDbProfile } = await import("./services/db.service.ts");
+      if (options.profile) {
+        setDbProfile(options.profile);
+      }
+      const { hasConfig, initProject } = await import("./cli/commands/init.ts");
+      if (!hasConfig()) {
+        await initProject();
+      }
+      const { startServer } = await import("./server/index.ts");
+      await startServer(options);
+    });
+
+  program
+    .command("stop")
+    .description("Stop the PPM server (supervisor stays alive)")
+    .option("-a, --all", "Kill all PPM and cloudflared processes (including untracked)")
+    .option("--kill", "Full shutdown (kills supervisor too)")
+    .action(async (options) => {
+      const { stopServer } = await import("./cli/commands/stop.ts");
+      await stopServer(options);
+    });
+
+  program
+    .command("down")
+    .description("Fully shut down PPM (supervisor + server + tunnel)")
+    .action(async () => {
+      const { stopServer } = await import("./cli/commands/stop.ts");
+      await stopServer({ kill: true });
+    });
+
+  program
+    .command("restart")
+    .description("Restart the server (keeps tunnel alive)")
+    .option("--force", "Force resume from paused state")
+    .action(async (options) => {
+      const { restartServer } = await import("./cli/commands/restart.ts");
+      await restartServer(options);
+    });
+
+  program
+    .command("status")
+    .description("Show PPM daemon status")
+    .option("-a, --all", "Show all PPM and cloudflared processes (including untracked)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { showStatus } = await import("./cli/commands/status.ts");
+      await showStatus(options);
+    });
+
+  program
+    .command("open")
+    .description("Open PPM in browser")
+    .action(async () => {
+      const { openBrowser } = await import("./cli/commands/open.ts");
+      await openBrowser();
+    });
+
+  program
+    .command("logs")
+    .description("View PPM daemon logs")
+    .option("-n, --tail <lines>", "Number of lines to show", "50")
+    .option("-f, --follow", "Follow log output")
+    .option("--clear", "Clear log file")
+    .action(async (options) => {
+      const { showLogs } = await import("./cli/commands/logs.ts");
+      await showLogs(options);
+    });
+
+  program
+    .command("report")
+    .description("Report a bug on GitHub (pre-fills env info + logs)")
+    .action(async () => {
+      const { reportBug } = await import("./cli/commands/report.ts");
+      await reportBug();
+    });
+
+  program
+    .command("init")
+    .description("Initialize PPM configuration (interactive or via flags)")
+    .option("-p, --port <port>", "Port to listen on")
+    .option("--scan <path>", "Directory to scan for git repos")
+    .option("--auth", "Enable authentication")
+    .option("--no-auth", "Disable authentication")
+    .option("--password <pw>", "Set access password")
+    .option("--share", "Pre-install cloudflared for sharing")
+    .option("-y, --yes", "Non-interactive mode (use defaults + flags)")
+    .action(async (options) => {
+      const { initProject } = await import("./cli/commands/init.ts");
+      await initProject(options);
+    });
+
+  const { registerProjectsCommands } = await import("./cli/commands/projects.ts");
+  registerProjectsCommands(program);
+
+  const { registerConfigCommands } = await import("./cli/commands/config-cmd.ts");
+  registerConfigCommands(program);
+
+  const { registerGitCommands } = await import("./cli/commands/git-cmd.ts");
+  registerGitCommands(program);
+
+  const { registerChatCommands } = await import("./cli/commands/chat-cmd.ts");
+  registerChatCommands(program);
+
+  program
+    .command("upgrade")
+    .description("Check for and install PPM updates")
+    .option("--check", "Only check for updates, don't install")
+    .action(async (options) => {
+      const { upgradeCmd } = await import("./cli/commands/upgrade.ts");
+      await upgradeCmd(options);
+    });
+
+  const { registerAutoStartCommands } = await import("./cli/commands/autostart.ts");
+  registerAutoStartCommands(program);
+
+  const { registerCloudCommands } = await import("./cli/commands/cloud.ts");
+  registerCloudCommands(program);
+
+  const { registerSkillsCommands } = await import("./cli/commands/skills-cmd.ts");
+  registerSkillsCommands(program);
+
+  const { registerExtCommands } = await import("./cli/commands/ext-cmd.ts");
+  registerExtCommands(program);
+
+  const { registerDbCommands } = await import("./cli/commands/db-cmd.ts");
+  registerDbCommands(program);
+
+  const { registerBotCommands } = await import("./cli/commands/bot-cmd.ts");
+  registerBotCommands(program);
+
+  const { registerJiraCommands } = await import("./cli/commands/jira-cmd.ts");
+  await registerJiraCommands(program);
+
+  const { registerExportCommands } = await import("./cli/commands/export-cmd.ts");
+  registerExportCommands(program);
+
+  return program;
+}
+
+if (import.meta.main) {
+  const program = await buildProgram();
+  program.parse();
+}

package/src/server/index.ts

@@ -499,11 +499,15 @@ export async function startServer(options: {
       qr.generate(shareUrl, { small: true });
     }
 
-    // Auto-enable system service (systemd/launchd) for boot resilience
+    // Auto-enable system service (systemd/launchd) for boot resilience.
+    // Also regenerates a stale unit file (missing Type=notify) so users who
+    // upgrade past the v0.13 → v0.14 systemd cgroup fix get the new unit
+    // picked up on next `systemctl --user restart ppm.service` / reboot.
     try {
-      const { getAutoStartStatus, enableAutoStart } = await import("../services/autostart-register.ts");
+      const { getAutoStartStatus, enableAutoStart, isAutoStartUnitStale } = await import("../services/autostart-register.ts");
       const status = getAutoStartStatus();
-      if (!status.enabled) {
+      const stale = status.enabled && isAutoStartUnitStale();
+      if (!status.enabled || stale) {
         const autoConfig = {
           port, host,
           share: !!options.share,
@@ -511,7 +515,11 @@ export async function startServer(options: {
         };
         // skipStart: supervisor is already running from direct spawn above
         await enableAutoStart(autoConfig, { skipStart: true });
-        console.log(`  ✓  Auto-restart enabled (${status.platform}). Disable: ppm autostart disable`);
+        if (stale) {
+          console.log(`  ↻  Auto-restart config migrated (Type=notify). Run 'systemctl --user restart ppm.service' to apply.`);
+        } else {
+          console.log(`  ✓  Auto-restart enabled (${status.platform}). Disable: ppm autostart disable`);
+        }
       }
     } catch {}
 

package/src/services/autostart-generator.ts

@@ -125,10 +125,12 @@ After=network-online.target
 Wants=network-online.target
 
 [Service]
-Type=simple
+Type=notify
+NotifyAccess=all
 ExecStart=${execStart}
 Restart=on-failure
 RestartSec=5
+TimeoutStartSec=60
 TimeoutStopSec=10
 KillMode=mixed
 ${envPath}

package/src/services/autostart-register.ts

@@ -350,4 +350,21 @@ export function getAutoStartStatus(): AutoStartStatus {
   };
 }
 
+/**
+ * Detect whether an existing systemd unit file is outdated and needs
+ * regeneration. Currently flags units missing Type=notify (introduced to fix
+ * the WSL/systemd upgrade-kill bug). Linux-only; returns false elsewhere.
+ */
+export function isAutoStartUnitStale(): boolean {
+  if (process.platform !== "linux") return false;
+  try {
+    const path = getServicePath();
+    if (!existsSync(path)) return false;
+    const content = readFileSync(path, "utf-8");
+    return !content.includes("Type=notify");
+  } catch {
+    return false;
+  }
+}
+
 export { loadMetadata, METADATA_FILE };

package/src/services/sd-notify.ts

@@ -0,0 +1,27 @@
+/**
+ * sd_notify helper — forwards messages to systemd via the `systemd-notify` binary.
+ * No-op on non-systemd platforms (NOTIFY_SOCKET unset).
+ *
+ * Usage:
+ *   await sdNotify("READY=1");                   // mark unit active (Type=notify)
+ *   await sdNotify(`MAINPID=${newPid}`);         // handoff main process (NotifyAccess=all)
+ *
+ * Shelling out to `systemd-notify` avoids implementing AF_UNIX SOCK_DGRAM
+ * transport in Node/Bun (not supported by node:dgram). The binary ships with
+ * systemd itself, so availability matches systemd availability.
+ */
+export async function sdNotify(state: string): Promise<void> {
+  if (!process.env.NOTIFY_SOCKET) return; // not running under systemd
+  try {
+    const proc = Bun.spawn({
+      cmd: ["systemd-notify", state],
+      stdio: ["ignore", "ignore", "ignore"],
+      env: process.env,
+    });
+    await proc.exited;
+  } catch {
+    // best-effort: if systemd-notify is missing, startup still proceeds
+    // (Type=notify units without READY=1 will time out, but that's already
+    // the failure mode — this helper doesn't make it worse).
+  }
+}

package/src/services/skill-export/backup-existing.ts

@@ -0,0 +1,33 @@
+// Rename existing skill files to `.bak-<timestamp>` before overwriting.
+// Preserves earlier backups by embedding a UTC timestamp in the suffix.
+import { existsSync, renameSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+/** Produce a compact UTC timestamp like `202604211733` (YYYYMMDDHHmm). */
+export function makeTimestamp(d: Date = new Date()): string {
+  return d.toISOString().replace(/[-:T]/g, "").slice(0, 12);
+}
+
+export function backupExisting(targetDir: string, ts: string = makeTimestamp()): string[] {
+  if (!existsSync(targetDir)) return [];
+  const backedUp: string[] = [];
+  walkAndBackup(targetDir, ts, backedUp);
+  return backedUp;
+}
+
+function walkAndBackup(dir: string, ts: string, collected: string[]): void {
+  const entries = readdirSync(dir);
+  for (const name of entries) {
+    // Skip already-backed-up files to avoid `.md.bak-X.bak-Y` chains.
+    if (name.includes(".bak-")) continue;
+    const abs = resolve(dir, name);
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      walkAndBackup(abs, ts, collected);
+    } else if (st.isFile() && name.endsWith(".md")) {
+      const dest = `${abs}.bak-${ts}`;
+      renameSync(abs, dest);
+      collected.push(dest);
+    }
+  }
+}

package/src/services/skill-export/copy-bundled-skill.ts

@@ -0,0 +1,36 @@
+// Recursive copy of the bundled skill package to a target directory.
+// Skips any stale `.bak-*` files in source (defensive, should not occur in bundle).
+import { cpSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync } from "node:fs";
+import { resolve, relative } from "node:path";
+
+export function copyBundledSkill(sourceDir: string, targetDir: string): string[] {
+  if (!existsSync(sourceDir)) {
+    throw new Error(`Source skill dir not found: ${sourceDir}`);
+  }
+  mkdirSync(targetDir, { recursive: true });
+  const copied: string[] = [];
+  walk(sourceDir, sourceDir, targetDir, copied);
+  return copied;
+}
+
+function walk(rootSrc: string, dir: string, targetRoot: string, collected: string[]): void {
+  for (const name of readdirSync(dir)) {
+    if (name.includes(".bak-")) continue;
+    const abs = resolve(dir, name);
+    const rel = relative(rootSrc, abs);
+    const dest = resolve(targetRoot, rel);
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      mkdirSync(dest, { recursive: true });
+      walk(rootSrc, abs, targetRoot, collected);
+    } else if (st.isFile()) {
+      copyFileSync(abs, dest);
+      collected.push(dest);
+    }
+  }
+}
+
+// Fallback single-shot copy using Node 16.7+ cpSync (kept in case walk is bypassed).
+export function copyTree(src: string, dest: string): void {
+  cpSync(src, dest, { recursive: true });
+}

package/src/services/skill-export/generate-db-schema.ts

@@ -0,0 +1,66 @@
+// Runtime: read the user's PPM SQLite config DB (readonly) and render a markdown schema doc.
+// Never opens the DB read-write. Gracefully handles missing DB.
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { Database } from "bun:sqlite";
+import { getPpmDir } from "../ppm-dir.ts";
+
+interface ColumnInfo {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+
+interface TableRow {
+  name: string;
+}
+
+export function generateDbSchemaMarkdown(dbPath?: string): string {
+  const path = dbPath ?? resolve(getPpmDir(), "ppm.db");
+  const header = "# PPM Database Schema\n\n_Auto-generated at install time from your local config DB._\n";
+
+  if (!existsSync(path)) {
+    return `${header}\n_Database not found at \`${path}\`. Run \`ppm init\` to create it._\n`;
+  }
+
+  let db: Database | null = null;
+  try {
+    db = new Database(path, { readonly: true });
+    const tables = db
+      .query<TableRow, []>("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name")
+      .all();
+
+    if (tables.length === 0) {
+      return `${header}\n_No tables found in \`${path}\`._\n`;
+    }
+
+    const parts: string[] = [header, ""];
+    parts.push(`Source: \`${path}\``);
+    parts.push("");
+
+    for (const t of tables) {
+      parts.push(`## ${t.name}`);
+      parts.push("");
+      const cols = db.query<ColumnInfo, []>(`PRAGMA table_info("${t.name}")`).all();
+      parts.push("| Column | Type | Nullable | PK | Default |");
+      parts.push("|---|---|---|---|---|");
+      for (const c of cols) {
+        const nullable = c.notnull === 0 ? "yes" : "no";
+        const pk = c.pk > 0 ? "yes" : "";
+        const def = c.dflt_value !== null ? `\`${c.dflt_value}\`` : "";
+        parts.push(`| \`${c.name}\` | \`${c.type || "—"}\` | ${nullable} | ${pk} | ${def} |`);
+      }
+      parts.push("");
+    }
+
+    return parts.join("\n") + "\n";
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return `${header}\n_Failed to read database at \`${path}\`: ${msg}_\n`;
+  } finally {
+    db?.close();
+  }
+}

package/src/services/skill-export/index.ts

@@ -0,0 +1,6 @@
+// Barrel re-exports for the skill-export service.
+export { resolveTargetDir, type SkillScope, type ResolveTargetOpts } from "./resolve-target-dir.ts";
+export { resolveAssetsDir } from "./resolve-assets-dir.ts";
+export { backupExisting, makeTimestamp } from "./backup-existing.ts";
+export { copyBundledSkill } from "./copy-bundled-skill.ts";
+export { generateDbSchemaMarkdown } from "./generate-db-schema.ts";

package/src/services/skill-export/resolve-assets-dir.ts

@@ -0,0 +1,31 @@
+// Resolve the bundled skill assets dir. Works both in dev (`bun src/index.ts`)
+// and installed npm package. Throws a clear error if assets are missing.
+import { fileURLToPath } from "node:url";
+import { resolve, dirname } from "node:path";
+import { existsSync } from "node:fs";
+
+const ASSETS_REL = "assets/skills/ppm";
+
+/**
+ * Walks up from this file to find the repo/package root that contains
+ * `assets/skills/ppm/SKILL.md`. Covers both:
+ *   - dev:     src/services/skill-export/*.ts      → repo root is ../../..
+ *   - bundled: compiled binary walks up similarly when `bun build --compile` preserves structure
+ */
+export function resolveAssetsDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(here, "../../..", ASSETS_REL),
+    resolve(here, "../..", ASSETS_REL),
+    resolve(here, "..", ASSETS_REL),
+    resolve(process.cwd(), ASSETS_REL),
+  ];
+  for (const c of candidates) {
+    if (existsSync(resolve(c, "SKILL.md"))) return c;
+  }
+  throw new Error(
+    `Bundled PPM skill assets not found. Searched:\n  ${candidates.join(
+      "\n  ",
+    )}\nRun \`bun run generate:skill\` (dev) or reinstall PPM.`,
+  );
+}

package/src/services/skill-export/resolve-target-dir.ts

@@ -0,0 +1,17 @@
+// Resolve the install target directory based on scope/output flags.
+// Precedence: --output > --scope project > --scope user (default).
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+export type SkillScope = "user" | "project";
+
+export interface ResolveTargetOpts {
+  scope?: SkillScope;
+  output?: string;
+}
+
+export function resolveTargetDir(opts: ResolveTargetOpts): string {
+  if (opts.output) return resolve(opts.output);
+  if (opts.scope === "project") return resolve(process.cwd(), ".claude/skills/ppm");
+  return resolve(homedir(), ".claude/skills/ppm");
+}