@donkeylabs/cli 2.0.16 → 2.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/cli",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "type": "module",
   "description": "CLI for @donkeylabs/server - project scaffolding and code generation",
   "main": "./src/index.ts",

package/src/commands/docs.ts

@@ -0,0 +1,207 @@
+/**
+ * Docs Command
+ *
+ * Syncs documentation from the installed @donkeylabs/server package
+ * to the user's project. This ensures users always have access to
+ * the latest documentation for their installed version.
+ *
+ * Usage:
+ *   donkeylabs docs           # Sync all docs to ./docs/donkeylabs/
+ *   donkeylabs docs --list    # List available docs
+ *   donkeylabs docs workflows # Sync specific doc
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } from "fs";
+import { join, dirname } from "path";
+import pc from "picocolors";
+
+const DEFAULT_DOCS_DIR = "docs/donkeylabs";
+
+interface DocsCommandOptions {
+  list?: boolean;
+  output?: string;
+}
+
+/**
+ * Find the docs directory from installed @donkeylabs/server
+ */
+function findDocsPath(): string | null {
+  // Try common locations
+  const possiblePaths = [
+    // node_modules (standard install)
+    join(process.cwd(), "node_modules", "@donkeylabs", "server", "docs"),
+    // bun's .bun cache
+    join(process.cwd(), "node_modules", ".bun", "@donkeylabs", "server", "docs"),
+    // Workspace/monorepo
+    join(process.cwd(), "..", "server", "docs"),
+    join(process.cwd(), "..", "..", "packages", "server", "docs"),
+  ];
+
+  for (const path of possiblePaths) {
+    if (existsSync(path) && statSync(path).isDirectory()) {
+      return path;
+    }
+  }
+
+  // Try to resolve from require
+  try {
+    const serverPkgPath = require.resolve("@donkeylabs/server/package.json", {
+      paths: [process.cwd()],
+    });
+    const serverDir = dirname(serverPkgPath);
+    const docsPath = join(serverDir, "docs");
+    if (existsSync(docsPath)) {
+      return docsPath;
+    }
+  } catch {
+    // Package not found
+  }
+
+  return null;
+}
+
+/**
+ * Get list of available doc files
+ */
+function getAvailableDocs(docsPath: string): string[] {
+  return readdirSync(docsPath)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(".md", ""));
+}
+
+/**
+ * Sync a single doc file
+ */
+function syncDoc(docsPath: string, docName: string, outputDir: string): boolean {
+  const sourcePath = join(docsPath, `${docName}.md`);
+  if (!existsSync(sourcePath)) {
+    return false;
+  }
+
+  const content = readFileSync(sourcePath, "utf-8");
+  const outputPath = join(outputDir, `${docName}.md`);
+
+  // Create output directory if needed
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  writeFileSync(outputPath, content);
+  return true;
+}
+
+/**
+ * Sync all docs
+ */
+function syncAllDocs(docsPath: string, outputDir: string): number {
+  const docs = getAvailableDocs(docsPath);
+  let synced = 0;
+
+  for (const doc of docs) {
+    if (syncDoc(docsPath, doc, outputDir)) {
+      synced++;
+    }
+  }
+
+  return synced;
+}
+
+/**
+ * Get version from installed package
+ */
+function getInstalledVersion(): string | null {
+  try {
+    const pkgPath = require.resolve("@donkeylabs/server/package.json", {
+      paths: [process.cwd()],
+    });
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
+export async function docsCommand(args: string[], options: DocsCommandOptions = {}): Promise<void> {
+  const docsPath = findDocsPath();
+
+  if (!docsPath) {
+    console.error(pc.red("Error: Could not find @donkeylabs/server docs."));
+    console.log(pc.dim("Make sure @donkeylabs/server is installed in your project."));
+    console.log(pc.dim("\nRun: bun add @donkeylabs/server"));
+    process.exit(1);
+  }
+
+  const version = getInstalledVersion();
+  const availableDocs = getAvailableDocs(docsPath);
+
+  // List mode
+  if (options.list || args[0] === "--list" || args[0] === "-l") {
+    console.log(pc.bold("\nAvailable Documentation"));
+    console.log(pc.dim(`Version: ${version || "unknown"}\n`));
+
+    // Group docs by category
+    const categories: Record<string, string[]> = {
+      "Core Services": ["logger", "cache", "events", "cron", "jobs", "external-jobs", "processes", "workflows", "sse", "rate-limiter", "errors"],
+      "API": ["router", "handlers", "middleware"],
+      "Server": ["lifecycle-hooks", "services", "core-services"],
+      "Infrastructure": ["database", "plugins", "sveltekit-adapter", "api-client"],
+      "Testing": ["testing"],
+      "Other": [],
+    };
+
+    // Categorize docs
+    const categorized = new Set<string>();
+    for (const [category, docs] of Object.entries(categories)) {
+      const matching = availableDocs.filter((d) => docs.includes(d));
+      if (matching.length > 0) {
+        console.log(pc.cyan(`  ${category}:`));
+        for (const doc of matching) {
+          console.log(`    ${pc.green("•")} ${doc}`);
+          categorized.add(doc);
+        }
+        console.log();
+      }
+    }
+
+    // Uncategorized
+    const uncategorized = availableDocs.filter((d) => !categorized.has(d));
+    if (uncategorized.length > 0) {
+      console.log(pc.cyan("  Other:"));
+      for (const doc of uncategorized) {
+        console.log(`    ${pc.green("•")} ${doc}`);
+      }
+      console.log();
+    }
+
+    console.log(pc.dim(`\nUsage:`));
+    console.log(pc.dim(`  donkeylabs docs           # Sync all docs`));
+    console.log(pc.dim(`  donkeylabs docs workflows # Sync specific doc`));
+    return;
+  }
+
+  const outputDir = options.output || DEFAULT_DOCS_DIR;
+  const specificDoc = args[0];
+
+  // Sync specific doc
+  if (specificDoc && specificDoc !== "--list" && specificDoc !== "-l") {
+    if (!availableDocs.includes(specificDoc)) {
+      console.error(pc.red(`Error: Doc "${specificDoc}" not found.`));
+      console.log(pc.dim(`\nAvailable docs: ${availableDocs.join(", ")}`));
+      console.log(pc.dim(`\nRun: donkeylabs docs --list`));
+      process.exit(1);
+    }
+
+    syncDoc(docsPath, specificDoc, outputDir);
+    console.log(pc.green(`✓ Synced ${specificDoc}.md to ${outputDir}/`));
+    return;
+  }
+
+  // Sync all docs
+  console.log(pc.bold("\nSyncing Documentation"));
+  console.log(pc.dim(`Version: ${version || "unknown"}`));
+  console.log(pc.dim(`Source: ${docsPath}`));
+  console.log(pc.dim(`Target: ${outputDir}/\n`));
+
+  const synced = syncAllDocs(docsPath, outputDir);
+
+  console.log(pc.green(`\n✓ Synced ${synced} documentation files to ${outputDir}/`));
+  console.log(pc.dim(`\nTip: Add ${outputDir}/ to your .gitignore if you don't want to commit docs.`));
+}

package/src/commands/update.ts

@@ -0,0 +1,360 @@
+/**
+ * Update Command
+ *
+ * Check for and install updates to @donkeylabs packages.
+ *
+ * Usage:
+ *   donkeylabs update           # Interactive update selection
+ *   donkeylabs update --all     # Update all packages
+ *   donkeylabs update --check   # Check for updates only (no install)
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import pc from "picocolors";
+
+const DONKEYLABS_PACKAGES = [
+  "@donkeylabs/server",
+  "@donkeylabs/adapter-sveltekit",
+  "@donkeylabs/cli",
+  "@donkeylabs/mcp",
+  "@donkeylabs/adapter-serverless",
+];
+
+interface PackageInfo {
+  name: string;
+  currentVersion: string | null;
+  latestVersion: string | null;
+  hasUpdate: boolean;
+  isDev: boolean;
+}
+
+interface UpdateOptions {
+  all?: boolean;
+  check?: boolean;
+  skipDocs?: boolean;
+}
+
+/**
+ * Get installed version from package.json
+ */
+function getInstalledPackages(packageJsonPath: string): Map<string, { version: string; isDev: boolean }> {
+  const installed = new Map<string, { version: string; isDev: boolean }>();
+
+  if (!existsSync(packageJsonPath)) {
+    return installed;
+  }
+
+  const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+  // Check dependencies
+  if (pkg.dependencies) {
+    for (const [name, version] of Object.entries(pkg.dependencies)) {
+      if (DONKEYLABS_PACKAGES.includes(name)) {
+        installed.set(name, { version: String(version), isDev: false });
+      }
+    }
+  }
+
+  // Check devDependencies
+  if (pkg.devDependencies) {
+    for (const [name, version] of Object.entries(pkg.devDependencies)) {
+      if (DONKEYLABS_PACKAGES.includes(name)) {
+        installed.set(name, { version: String(version), isDev: true });
+      }
+    }
+  }
+
+  return installed;
+}
+
+/**
+ * Get latest version from npm registry
+ */
+async function getLatestVersion(packageName: string): Promise<string | null> {
+  try {
+    const result = execSync(`npm view ${packageName} version 2>/dev/null`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse version string (handles workspace:*, ^, ~, etc.)
+ */
+function parseVersion(version: string): string {
+  if (version.startsWith("workspace:")) {
+    return "workspace";
+  }
+  // Remove ^, ~, >=, etc.
+  return version.replace(/^[\^~>=<]+/, "");
+}
+
+/**
+ * Compare versions (simple semver comparison)
+ */
+function isNewerVersion(current: string, latest: string): boolean {
+  if (current === "workspace") return false;
+
+  const currentParts = current.split(".").map(Number);
+  const latestParts = latest.split(".").map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const c = currentParts[i] || 0;
+    const l = latestParts[i] || 0;
+    if (l > c) return true;
+    if (l < c) return false;
+  }
+
+  return false;
+}
+
+/**
+ * Check for updates
+ */
+async function checkForUpdates(packageJsonPath: string): Promise<PackageInfo[]> {
+  const installed = getInstalledPackages(packageJsonPath);
+  const packages: PackageInfo[] = [];
+
+  console.log(pc.dim("\nChecking for updates...\n"));
+
+  for (const name of DONKEYLABS_PACKAGES) {
+    const info = installed.get(name);
+
+    if (!info) {
+      continue; // Not installed
+    }
+
+    const currentVersion = parseVersion(info.version);
+    const latestVersion = await getLatestVersion(name);
+
+    const hasUpdate = latestVersion
+      ? isNewerVersion(currentVersion, latestVersion)
+      : false;
+
+    packages.push({
+      name,
+      currentVersion,
+      latestVersion,
+      hasUpdate,
+      isDev: info.isDev,
+    });
+  }
+
+  return packages;
+}
+
+/**
+ * Display update status
+ */
+function displayUpdateStatus(packages: PackageInfo[]): void {
+  const hasUpdates = packages.some((p) => p.hasUpdate);
+
+  console.log(pc.bold("Package Status\n"));
+
+  for (const pkg of packages) {
+    const statusIcon = pkg.hasUpdate
+      ? pc.yellow("⬆")
+      : pc.green("✓");
+
+    const versionInfo = pkg.hasUpdate
+      ? `${pc.dim(pkg.currentVersion)} → ${pc.green(pkg.latestVersion)}`
+      : pc.dim(pkg.currentVersion || "unknown");
+
+    const devBadge = pkg.isDev ? pc.dim(" (dev)") : "";
+
+    console.log(`  ${statusIcon} ${pkg.name}${devBadge}`);
+    console.log(`    ${versionInfo}\n`);
+  }
+
+  if (!hasUpdates) {
+    console.log(pc.green("All packages are up to date!"));
+  }
+}
+
+/**
+ * Interactive package selection using simple prompt
+ */
+async function selectPackagesToUpdate(packages: PackageInfo[]): Promise<PackageInfo[]> {
+  const updatable = packages.filter((p) => p.hasUpdate);
+
+  if (updatable.length === 0) {
+    return [];
+  }
+
+  console.log(pc.bold("\nSelect packages to update:\n"));
+
+  // Display options
+  console.log(`  ${pc.cyan("0)")} Update all packages`);
+  updatable.forEach((pkg, i) => {
+    console.log(
+      `  ${pc.cyan(`${i + 1})`)} ${pkg.name} ${pc.dim(`${pkg.currentVersion} → ${pkg.latestVersion}`)}`
+    );
+  });
+  console.log(`  ${pc.cyan("s)")} Skip update\n`);
+
+  // Read input
+  process.stdout.write(pc.bold("Enter selection (0-" + updatable.length + ", or s): "));
+
+  const input = await new Promise<string>((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.once("data", (chunk) => {
+      data = chunk.toString().trim();
+      resolve(data);
+    });
+    process.stdin.resume();
+  });
+
+  process.stdin.pause();
+
+  if (input.toLowerCase() === "s") {
+    return [];
+  }
+
+  if (input === "0") {
+    return updatable;
+  }
+
+  const index = parseInt(input, 10);
+  if (index >= 1 && index <= updatable.length) {
+    return [updatable[index - 1]];
+  }
+
+  console.log(pc.yellow("\nInvalid selection, skipping update."));
+  return [];
+}
+
+/**
+ * Update package.json with new versions
+ */
+function updatePackageJson(
+  packageJsonPath: string,
+  packagesToUpdate: PackageInfo[]
+): void {
+  const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+  for (const pkgInfo of packagesToUpdate) {
+    const versionString = `^${pkgInfo.latestVersion}`;
+
+    if (pkgInfo.isDev && pkg.devDependencies?.[pkgInfo.name]) {
+      pkg.devDependencies[pkgInfo.name] = versionString;
+    } else if (pkg.dependencies?.[pkgInfo.name]) {
+      pkg.dependencies[pkgInfo.name] = versionString;
+    }
+  }
+
+  writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+/**
+ * Run bun install
+ */
+function runInstall(): void {
+  console.log(pc.dim("\nRemoving node_modules..."));
+  const nodeModulesPath = join(process.cwd(), "node_modules");
+  if (existsSync(nodeModulesPath)) {
+    rmSync(nodeModulesPath, { recursive: true, force: true });
+  }
+
+  // Also remove bun.lock for clean install
+  const bunLockPath = join(process.cwd(), "bun.lock");
+  if (existsSync(bunLockPath)) {
+    rmSync(bunLockPath);
+  }
+
+  console.log(pc.dim("Running bun install...\n"));
+  execSync("bun install", { stdio: "inherit" });
+}
+
+/**
+ * Sync documentation
+ */
+async function syncDocs(): Promise<void> {
+  console.log(pc.dim("\nSyncing documentation..."));
+
+  try {
+    const { docsCommand } = await import("./docs");
+    await docsCommand([], {});
+  } catch (error) {
+    console.log(pc.yellow("Could not sync docs (this is optional)"));
+  }
+}
+
+export async function updateCommand(
+  args: string[],
+  options: UpdateOptions = {}
+): Promise<void> {
+  const packageJsonPath = join(process.cwd(), "package.json");
+
+  if (!existsSync(packageJsonPath)) {
+    console.error(pc.red("Error: No package.json found in current directory."));
+    process.exit(1);
+  }
+
+  // Check for updates
+  const packages = await checkForUpdates(packageJsonPath);
+
+  if (packages.length === 0) {
+    console.log(pc.yellow("No @donkeylabs packages found in this project."));
+    console.log(pc.dim("\nInstall with: bun add @donkeylabs/server"));
+    return;
+  }
+
+  // Display status
+  displayUpdateStatus(packages);
+
+  // Check-only mode
+  if (options.check || args.includes("--check") || args.includes("-c")) {
+    return;
+  }
+
+  const updatable = packages.filter((p) => p.hasUpdate);
+
+  if (updatable.length === 0) {
+    return;
+  }
+
+  // Select packages to update
+  let packagesToUpdate: PackageInfo[];
+
+  if (options.all || args.includes("--all") || args.includes("-a")) {
+    packagesToUpdate = updatable;
+  } else {
+    packagesToUpdate = await selectPackagesToUpdate(packages);
+  }
+
+  if (packagesToUpdate.length === 0) {
+    console.log(pc.dim("\nNo packages selected for update."));
+    return;
+  }
+
+  // Confirm
+  console.log(pc.bold("\nUpdating packages:"));
+  for (const pkg of packagesToUpdate) {
+    console.log(`  • ${pkg.name} → ${pc.green(pkg.latestVersion)}`);
+  }
+
+  // Update package.json
+  console.log(pc.dim("\nUpdating package.json..."));
+  updatePackageJson(packageJsonPath, packagesToUpdate);
+
+  // Run install
+  runInstall();
+
+  // Sync docs
+  if (!options.skipDocs && !args.includes("--skip-docs")) {
+    await syncDocs();
+  }
+
+  console.log(pc.green("\n✓ Update complete!"));
+  console.log(pc.dim("\nUpdated packages:"));
+  for (const pkg of packagesToUpdate) {
+    console.log(`  ${pc.green("•")} ${pkg.name}@${pkg.latestVersion}`);
+  }
+}

package/src/index.ts

@@ -18,6 +18,11 @@ const { positionals, values } = parseArgs({
     version: { type: "boolean", short: "v" },
     type: { type: "string", short: "t" },
     local: { type: "boolean", short: "l" },
+    list: { type: "boolean" },
+    output: { type: "string", short: "o" },
+    all: { type: "boolean", short: "a" },
+    check: { type: "boolean", short: "c" },
+    "skip-docs": { type: "boolean" },
   },
   allowPositionals: true,
 });
@@ -37,6 +42,8 @@ ${pc.bold("Commands:")}
   ${pc.cyan("add")}               Add optional plugins (images, auth, etc.)
   ${pc.cyan("generate")}          Generate types (registry, context, client)
   ${pc.cyan("plugin")}            Plugin management
+  ${pc.cyan("update")}            Check and install package updates
+  ${pc.cyan("docs")}              Sync documentation from installed package
   ${pc.cyan("deploy")} <platform> Deploy (vercel, cloudflare, aws, vps)
   ${pc.cyan("deploy history")}     Show deployment history
   ${pc.cyan("deploy rollback")}    Rollback to version
@@ -57,6 +64,11 @@ ${pc.bold("Options:")}
    donkeylabs init --type sveltekit # SvelteKit + adapter project
    donkeylabs generate
    donkeylabs plugin create myPlugin
+   donkeylabs update                # Interactive package update
+   donkeylabs update --check        # Check for updates only
+   donkeylabs update --all          # Update all packages
+   donkeylabs docs                  # Sync all docs to ./docs/donkeylabs/
+   donkeylabs docs --list           # List available docs
    donkeylabs deploy vercel         # Deploy to Vercel
    donkeylabs config                # Interactive configuration
    donkeylabs config set DATABASE_URL postgresql://...
@@ -113,6 +125,20 @@ async function main() {
       await mcpCommand(positionals.slice(1));
       break;
 
+    case "docs":
+      const { docsCommand } = await import("./commands/docs");
+      await docsCommand(positionals.slice(1), { list: values.list, output: values.output });
+      break;
+
+    case "update":
+      const { updateCommand } = await import("./commands/update");
+      await updateCommand(positionals.slice(1), {
+        all: values.all,
+        check: values.check,
+        skipDocs: values["skip-docs"],
+      });
+      break;
+
     case "deploy":
       const subcommand = positionals[1];
       if (subcommand === "history") {