@hienlh/ppm 0.12.11 → 0.13.0

package/scripts/lib/generate-cli-reference.ts

@@ -0,0 +1,81 @@
+// Walk the Commander tree produced by buildProgram() and emit a markdown reference.
+// No side effects — buildProgram() assembles commands but does not invoke any `action` callback.
+import type { Command, Option } from "commander";
+import { buildProgram } from "../../src/index.ts";
+import type { OutputFile } from "./write-output.ts";
+
+export async function generateCliReference(_root: string): Promise<OutputFile[]> {
+  const program = await buildProgram();
+  const header = "# PPM CLI Reference\n\n_Auto-generated. Do not edit._\n\nRoot binary: `ppm`. Run `ppm <command> --help` for full usage.\n";
+
+  // Global options section (root-level options only, excluding implicit -V/-h).
+  const globalOptsMd = renderRootOptions(program);
+
+  // Child commands sorted alphabetically for deterministic output.
+  const children = [...program.commands].filter((c) => !isHidden(c)).sort((a, b) => a.name().localeCompare(b.name()));
+  const sections = children.map((c) => renderCommand(c, 2)).join("\n");
+
+  const content = `${header}\n${globalOptsMd}\n## Commands\n\n${sections}`;
+  return [{ relPath: "references/cli-reference.md", content }];
+}
+
+function isHidden(cmd: Command): boolean {
+  // Commander's internal flag. Public typings omit `_hidden`; access defensively.
+  return Boolean((cmd as unknown as { _hidden?: boolean })._hidden);
+}
+
+function renderRootOptions(program: Command): string {
+  const opts = program.options.filter((o) => !o.hidden);
+  if (opts.length === 0) return "";
+  const rows = opts.map((o) => `- \`${o.flags}\` — ${o.description || "_(no description)_"}`).join("\n");
+  return `## Global Options\n\n${rows}\n`;
+}
+
+function renderCommand(cmd: Command, depth: number): string {
+  const heading = "#".repeat(Math.min(depth, 6));
+  const pathName = commandPath(cmd);
+  const desc = cmd.description() || "_(no description)_";
+
+  const parts: string[] = [];
+  parts.push(`${heading} \`ppm ${pathName}\``);
+  parts.push("");
+  parts.push(desc);
+
+  const opts = cmd.options.filter((o: Option) => !o.hidden);
+  if (opts.length > 0) {
+    parts.push("");
+    parts.push("**Options:**");
+    for (const o of opts) {
+      const d = o.description || "_(no description)_";
+      const def = o.defaultValue !== undefined ? ` (default: \`${JSON.stringify(o.defaultValue)}\`)` : "";
+      parts.push(`- \`${o.flags}\` — ${d}${def}`);
+    }
+  }
+
+  const usage = cmd.usage();
+  if (usage && usage !== "[options]") {
+    parts.push("");
+    parts.push(`**Usage:** \`ppm ${pathName} ${usage}\``);
+  }
+
+  parts.push("");
+
+  // Recurse into subcommands (preserve registration order per phase 2 spec).
+  const subs = cmd.commands.filter((c) => !isHidden(c));
+  for (const sub of subs) {
+    parts.push(renderCommand(sub, depth + 1));
+  }
+
+  return parts.join("\n");
+}
+
+function commandPath(cmd: Command): string {
+  // Walk up parents to construct e.g. `db list` instead of just `list`.
+  const chain: string[] = [];
+  let cur: Command | null = cmd;
+  while (cur && cur.parent) {
+    chain.unshift(cur.name());
+    cur = cur.parent;
+  }
+  return chain.join(" ");
+}

package/scripts/lib/generate-common-tasks.ts

@@ -0,0 +1,14 @@
+// Phase 4 populates. Phase 1 stub.
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { OutputFile } from "./write-output.ts";
+
+export function generateCommonTasks(root: string): OutputFile[] {
+  const tmplPath = resolve(root, "templates/skill/common-tasks.md");
+  if (existsSync(tmplPath)) {
+    const content = readFileSync(tmplPath, "utf-8");
+    return [{ relPath: "references/common-tasks.md", content }];
+  }
+  const stub = "# PPM Common Tasks\n\n_TODO: populated in phase 4._\n";
+  return [{ relPath: "references/common-tasks.md", content: stub }];
+}

package/scripts/lib/generate-http-api.ts

@@ -0,0 +1,145 @@
+// Static scan of Hono route definitions. Two-pass:
+//   1. Parse src/server/index.ts → mount map { mountPath: routerIdent } + import { routerIdent: relFile }.
+//   2. For each mounted route file, regex-scan HTTP method calls, group by mount prefix.
+// No code execution — all data comes from string parsing.
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { OutputFile } from "./write-output.ts";
+
+const METHOD_RE = /\.(get|post|put|patch|delete|all)\s*\(\s*["'`]([^"'`]+)["'`]/g;
+const MOUNT_RE = /\.route\s*\(\s*["'`]([^"'`]+)["'`]\s*,\s*(\w+)\s*\)/g;
+const IMPORT_RE = /import\s*\{\s*([\w,\s]+)\s*\}\s*from\s*["'`]([^"'`]+)["'`]/g;
+
+interface RouteEntry {
+  method: string;
+  path: string;
+  desc?: string;
+}
+
+export function generateHttpApi(root: string): OutputFile[] {
+  const serverIndexPath = resolve(root, "src/server/index.ts");
+  if (!existsSync(serverIndexPath)) {
+    return [{ relPath: "references/http-api.md", content: "# PPM HTTP API\n\n_Server index not found._\n" }];
+  }
+
+  const serverSrc = readFileSync(serverIndexPath, "utf-8");
+  const importMap = parseImports(serverSrc);
+  const mounts = parseMounts(serverSrc);
+
+  // Group routes by mount prefix
+  const grouped: Record<string, RouteEntry[]> = {};
+  const warnings: string[] = [];
+
+  for (const [prefix, routerIdent] of mounts) {
+    const rel = importMap.get(routerIdent);
+    if (!rel) {
+      warnings.push(`Unresolved import for router '${routerIdent}' (mount: ${prefix})`);
+      continue;
+    }
+    const routeFile = resolveImport(serverIndexPath, rel);
+    if (!existsSync(routeFile)) {
+      warnings.push(`Route file not found: ${routeFile} (router: ${routerIdent})`);
+      continue;
+    }
+    const entries = scanRoutes(readFileSync(routeFile, "utf-8"));
+    if (!grouped[prefix]) grouped[prefix] = [];
+    grouped[prefix].push(...entries);
+  }
+
+  // Build markdown
+  const parts: string[] = [];
+  parts.push("# PPM HTTP API");
+  parts.push("");
+  parts.push("_Auto-generated. Do not edit._");
+  parts.push("");
+  parts.push("_Base URL: `http://localhost:8080` (default; override via `ppm config set port <n>`)._");
+  parts.push("");
+
+  const sortedPrefixes = Object.keys(grouped).sort();
+  for (const prefix of sortedPrefixes) {
+    const routes = grouped[prefix];
+    if (!routes || routes.length === 0) continue;
+    parts.push(`## ${prefix || "/"}`);
+    parts.push("");
+    for (const r of routes) {
+      const fullPath = joinPath(prefix, r.path);
+      const method = r.method.toUpperCase().padEnd(6);
+      parts.push(`- \`${method} ${fullPath}\`${r.desc ? ` — ${r.desc}` : ""}`);
+    }
+    parts.push("");
+  }
+
+  parts.push("## WebSocket");
+  parts.push("");
+  parts.push("- `ws://<host>/ws/chat` — AI chat stream (Claude Agent SDK)");
+  parts.push("- `ws://<host>/ws/terminal` — PTY terminal multiplexer");
+  parts.push("- `ws://<host>/ws/extensions` — extension host channel");
+  parts.push("");
+
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8")) as { version: string };
+  parts.push(`<!-- Generated from src/server/routes/ for PPM v${pkg.version} -->`);
+
+  if (warnings.length > 0) {
+    parts.push("");
+    parts.push("<!--");
+    parts.push("Scanner warnings (build-time):");
+    for (const w of warnings) parts.push(`  - ${w}`);
+    parts.push("-->");
+  }
+
+  return [{ relPath: "references/http-api.md", content: parts.join("\n") + "\n" }];
+}
+
+function parseImports(src: string): Map<string, string> {
+  const map = new Map<string, string>();
+  let m: RegExpExecArray | null;
+  const re = new RegExp(IMPORT_RE);
+  while ((m = re.exec(src)) !== null) {
+    const ids = (m[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const path = m[2] ?? "";
+    for (const id of ids) map.set(id, path);
+  }
+  return map;
+}
+
+function parseMounts(src: string): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  let m: RegExpExecArray | null;
+  const re = new RegExp(MOUNT_RE);
+  while ((m = re.exec(src)) !== null) {
+    out.push([m[1] ?? "", m[2] ?? ""]);
+  }
+  return out;
+}
+
+function resolveImport(fromFile: string, spec: string): string {
+  // Resolve relative import from a source file. Preserve `.ts` suffix if present.
+  const fromDir = resolve(fromFile, "..");
+  let abs = resolve(fromDir, spec);
+  if (!abs.endsWith(".ts") && !abs.endsWith(".js")) {
+    abs += ".ts";
+  }
+  return abs;
+}
+
+function scanRoutes(src: string): RouteEntry[] {
+  const entries: RouteEntry[] = [];
+  let m: RegExpExecArray | null;
+  const re = new RegExp(METHOD_RE);
+  while ((m = re.exec(src)) !== null) {
+    const method = m[1] ?? "";
+    const path = m[2] ?? "";
+    // Skip obviously-bogus matches (e.g. "http://" in URLs — regex already avoids these since path can't start with http:).
+    if (path.startsWith("http:") || path.startsWith("https:")) continue;
+    entries.push({ method, path });
+  }
+  return entries;
+}
+
+function joinPath(prefix: string, routePath: string): string {
+  if (!prefix || prefix === "/") return routePath;
+  if (routePath === "/" || routePath === "") return prefix;
+  const p = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const r = routePath.startsWith("/") ? routePath : `/${routePath}`;
+  return p + r;
+}

package/scripts/lib/generate-skill-md.ts

@@ -0,0 +1,28 @@
+// Phase 4 populates. Phase 1 stub returns a placeholder SKILL.md.
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { OutputFile } from "./write-output.ts";
+
+export function generateSkillMd(root: string): OutputFile[] {
+  const tmplPath = resolve(root, "templates/skill/SKILL.md.tmpl");
+  if (existsSync(tmplPath)) {
+    const tmpl = readFileSync(tmplPath, "utf-8");
+    const pkgJson = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8")) as { version: string };
+    const footer = `<!-- Generated for PPM v${pkgJson.version} at build time. Re-run \`ppm export skill --install\` to refresh. -->`;
+    const content = tmpl.replace("<!-- AUTO:version_footer -->", footer);
+    return [{ relPath: "SKILL.md", content }];
+  }
+  // Stub fallback when template not yet authored (used during phase 1)
+  const stub = [
+    "---",
+    "name: ppm",
+    "description: Control PPM via CLI, HTTP API, and SQLite config DB.",
+    "---",
+    "",
+    "# PPM Skill",
+    "",
+    "_Stub — template pending (phase 4)._",
+    "",
+  ].join("\n");
+  return [{ relPath: "SKILL.md", content: stub }];
+}

package/scripts/lib/write-output.ts

@@ -0,0 +1,17 @@
+// Shared helper: recursively create dirs then write files. Used by skill package generator.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export interface OutputFile {
+  relPath: string;
+  content: string;
+}
+
+export function writeFiles(rootDir: string, files: OutputFile[]): void {
+  for (const f of files) {
+    const abs = resolve(rootDir, f.relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, f.content, "utf-8");
+  }
+  console.log(`[generate-ppm-skill] wrote ${files.length} files to ${rootDir}`);
+}

package/src/cli/commands/export-cmd.ts

@@ -0,0 +1,85 @@
+// `ppm export skill` — install bundled skill package to ~/.claude/skills/ppm/ (or custom path)
+// so external AI tools (Claude Code, compatible agents) can control PPM.
+import type { Command } from "commander";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  resolveTargetDir,
+  resolveAssetsDir,
+  backupExisting,
+  copyBundledSkill,
+  generateDbSchemaMarkdown,
+  type SkillScope,
+} from "../../services/skill-export/index.ts";
+
+interface ExportSkillOpts {
+  install?: boolean;
+  scope: SkillScope;
+  output?: string;
+  format: string;
+}
+
+export function registerExportCommands(program: Command): void {
+  const exp = program
+    .command("export")
+    .description("Export PPM metadata for external tools (AI agents, editors)");
+
+  exp
+    .command("skill")
+    .description("Export Claude Code skill for controlling PPM from external AI tools")
+    .option("--install", "Install to target dir (default scope=user → ~/.claude/skills/ppm/)")
+    .option("--scope <scope>", "Install scope: user | project", "user")
+    .option("--output <dir>", "Custom output directory (overrides --scope)")
+    .option("--format <fmt>", "Output format", "claude-code")
+    .action(async (opts: ExportSkillOpts) => {
+      if (opts.format !== "claude-code") {
+        console.error(`Unsupported format: ${opts.format}. Only 'claude-code' is supported in v1.`);
+        process.exit(1);
+      }
+      if (opts.scope && opts.scope !== "user" && opts.scope !== "project") {
+        console.error(`Invalid scope: ${opts.scope}. Use 'user' or 'project'.`);
+        process.exit(1);
+      }
+
+      let assetsDir: string;
+      try {
+        assetsDir = resolveAssetsDir();
+      } catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(2);
+      }
+
+      // Preview mode: print merged SKILL.md to stdout.
+      if (!opts.install && !opts.output) {
+        const skillPath = resolve(assetsDir, "SKILL.md");
+        process.stdout.write(readFileSync(skillPath, "utf-8"));
+        return;
+      }
+
+      const target = resolveTargetDir({ scope: opts.scope, output: opts.output });
+
+      try {
+        const backedUp = backupExisting(target);
+        mkdirSync(target, { recursive: true });
+        copyBundledSkill(assetsDir, target);
+
+        // Runtime DB schema (reads ~/.ppm/ppm.db readonly)
+        const refsDir = resolve(target, "references");
+        mkdirSync(refsDir, { recursive: true });
+        writeFileSync(resolve(refsDir, "db-schema.md"), generateDbSchemaMarkdown(), "utf-8");
+
+        console.log(`✓ Installed PPM skill → ${target}`);
+        if (backedUp.length > 0) {
+          console.log(`  Backed up ${backedUp.length} existing file(s) with .bak-<timestamp> suffix.`);
+          console.log(`  Safe to delete those backups if not needed.`);
+        }
+        if (!existsSync(resolve(target, "SKILL.md"))) {
+          console.error("Post-install verification failed: SKILL.md missing in target.");
+          process.exit(1);
+        }
+      } catch (e) {
+        console.error(`Install failed: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+}