pi-docparser 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows semantic versioning.
 
+## [1.1.0] - 2026-03-20
+
+### Changed
+
+- renamed the dependency diagnostic command from `/docparser-doctor` to `/docparser:doctor`
+- improved `/docparser:doctor` so missing dependencies are reported as normal diagnostics instead of error-style command failures
+- added a dedicated in-progress loader while automatic dependency installation commands are running
+- unified doctor install guidance and auto-install command generation, including correct Homebrew cask usage for LibreOffice on macOS
+
+## [1.0.1] - 2026-03-20
+
+### Changed
+
+- added Pi package gallery preview image metadata
+- added concrete `document_parse` usage examples to the README
+- added GitHub repository metadata to improve the npm package listing
+
 ## [1.0.0] - 2026-03-20
 
 Initial public release.

package/README.md

@@ -4,7 +4,7 @@ A standalone [pi](https://shittycodingagent.ai/) package that adds a `document_p
 
 It wraps [`@llamaindex/liteparse`](https://github.com/run-llama/liteparse) so pi can parse PDFs, Office documents, spreadsheets, CSV files, and common image formats through a dedicated tool instead of ad-hoc shell commands. It can also perform OCR.
 
-When required host tools such as LibreOffice, ImageMagick, or Ghostscript are missing, the tool surfaces actionable install guidance instead of generic conversion failures and points users to `/docparser-doctor` for guided setup.
+When required host tools such as LibreOffice, ImageMagick, or Ghostscript are missing, the tool surfaces actionable install guidance instead of generic conversion failures and points users to `/docparser:doctor` for guided setup.
 
 ## What this package provides
 
@@ -169,7 +169,7 @@ Some image or vector conversion paths may also require Ghostscript.
 If parsing fails because a host dependency is missing, the extension points users to:
 
 ```text
-/docparser-doctor
+/docparser:doctor
 ```
 
 Run it inside pi to:
@@ -178,13 +178,15 @@ Run it inside pi to:
 - check whether LibreOffice, ImageMagick, and Ghostscript are available
 - optionally focus the check on a specific file path
 - suggest the most appropriate install commands for the current machine
+- report missing packages as doctor findings instead of making the command look like it failed
+- keep the UI visibly busy while automatic install commands are running
 - optionally attempt those install commands after user confirmation when that looks safe to automate
 
 Examples:
 
 ```text
-/docparser-doctor
-/docparser-doctor @./slides.pptx
+/docparser:doctor
+/docparser:doctor @./slides.pptx
 ```
 
 ## Known limitations

package/extensions/docparser/constants.ts

@@ -58,14 +58,5 @@ export const IMAGE_EXTENSIONS = new Set([
 
 export const GHOSTSCRIPT_REQUIRED_EXTENSIONS = new Set([".svg", ".eps", ".ps", ".ai"]);
 
-export const LIBREOFFICE_MISSING_MESSAGE =
-  "LibreOffice is not installed. Please install LibreOffice to convert office documents. On macOS: brew install --cask libreoffice, On Ubuntu: apt-get install libreoffice, On Windows: choco install libreoffice-fresh";
-
-export const IMAGEMAGICK_MISSING_MESSAGE =
-  "ImageMagick is not installed. Please install ImageMagick to convert images. On macOS: brew install imagemagick, On Ubuntu: apt-get install imagemagick, On Windows: choco install imagemagick.app";
-
-export const GHOSTSCRIPT_MISSING_MESSAGE =
-  "Ghostscript is required to convert %s files but is not installed. On macOS: brew install ghostscript, On Ubuntu: apt-get install ghostscript, On Windows: choco install ghostscript";
-
-export const DOCTOR_COMMAND_NAME = "docparser-doctor";
+export const DOCTOR_COMMAND_NAME = "docparser:doctor";
 export const DOCTOR_COMMAND = `/${DOCTOR_COMMAND_NAME}`;

package/extensions/docparser/deps.ts

@@ -5,11 +5,8 @@ import { access } from "node:fs/promises";
 
 import {
   DOCTOR_COMMAND,
-  GHOSTSCRIPT_MISSING_MESSAGE,
   GHOSTSCRIPT_REQUIRED_EXTENSIONS,
-  IMAGEMAGICK_MISSING_MESSAGE,
   INSTALL_COMMAND_TIMEOUT_MS,
-  LIBREOFFICE_MISSING_MESSAGE,
 } from "./constants.ts";
 import type {
   DependencyDiagnosis,
@@ -82,6 +79,7 @@ const PACKAGE_NAMES: Record<PackageManagerId, Record<DependencyName, string>> =
     ghostscript: "ghostscript",
   },
 };
+const BREW_CASK_DEPENDENCIES = new Set<DependencyName>(["libreoffice"]);
 const LINUX_MANAGERS: Array<{ id: PackageManagerId; label: string }> = [
   { id: "apt-get", label: "APT" },
   { id: "dnf", label: "DNF" },
@@ -140,77 +138,10 @@ async function findFirstAvailableCommand(
   return undefined;
 }
 
-function formatGhostscriptMissingMessage(extension: string): string {
-  const fileTypeLabel = (extension || "vector").replace(/^\./, "").toUpperCase();
-  return GHOSTSCRIPT_MISSING_MESSAGE.replace("%s", fileTypeLabel);
-}
-
-const DEPENDENCY_METADATA: Record<
-  DependencyName,
-  {
-    label: string;
-    summary: string;
-    findCommand: () => Promise<string | undefined>;
-    getMissingMessage: (inspection?: InputInspection) => string;
-  }
-> = {
-  libreoffice: {
-    label: "LibreOffice",
-    summary:
-      "Needed for Office documents and spreadsheets such as DOCX, PPTX, XLSX, CSV, and similar formats.",
-    findCommand: () =>
-      findFirstAvailableCommand(
-        ["libreoffice", "soffice"],
-        process.platform === "darwin"
-          ? [
-              "/Applications/LibreOffice.app/Contents/MacOS/soffice",
-              "/Applications/LibreOffice.app/Contents/MacOS/libreoffice",
-            ]
-          : process.platform === "win32"
-            ? [
-                "C:\\Program Files\\LibreOffice\\program\\soffice.exe",
-                "C:\\Program Files\\LibreOffice\\program\\libreoffice.exe",
-                "C:\\Program Files (x86)\\LibreOffice\\program\\soffice.exe",
-                "C:\\Program Files (x86)\\LibreOffice\\program\\libreoffice.exe",
-              ]
-            : [],
-      ),
-    getMissingMessage: () => LIBREOFFICE_MISSING_MESSAGE,
-  },
-  imagemagick: {
-    label: "ImageMagick",
-    summary:
-      "Needed for image inputs such as PNG, JPG, TIFF, WebP, SVG, and similar formats that must be converted before parsing.",
-    findCommand: () =>
-      findFirstAvailableCommand(process.platform === "win32" ? ["magick"] : ["magick", "convert"]),
-    getMissingMessage: () => IMAGEMAGICK_MISSING_MESSAGE,
-  },
-  ghostscript: {
-    label: "Ghostscript",
-    summary:
-      "Needed for vector image conversion paths such as SVG, EPS, PS, and AI when ImageMagick delegates rendering.",
-    findCommand: () => findFirstAvailableCommand(["gs", "gswin64c", "gswin32c"]),
-    getMissingMessage: (inspection) =>
-      formatGhostscriptMissingMessage(inspection?.extension || ".svg"),
-  },
-};
-
 function getPackageNames(manager: PackageManagerId, dependencyNames: DependencyName[]): string[] {
   return dependencyNames.map((dependencyName) => PACKAGE_NAMES[manager][dependencyName]);
 }
 
-function getLinuxInstallArgs(managerId: PackageManagerId, packageNames: string[]): string[] {
-  if (managerId === "pacman") {
-    return ["-Sy", "--noconfirm", ...packageNames];
-  }
-
-  if (managerId === "apk") {
-    return ["add", ...packageNames];
-  }
-
-  return ["install", "-y", ...packageNames];
-}
-
 function buildCommandDisplay(command: string, args: string[], displayPrefix = ""): string {
   return `${displayPrefix}${command}${args.length > 0 ? ` ${args.join(" ")}` : ""}`;
 }
@@ -243,6 +174,52 @@ function createCommandSpec(
   };
 }
 
+function createDisplayCommand(manager: PackageManagerId, dependencyName: DependencyName): string {
+  if (manager === "brew" && BREW_CASK_DEPENDENCIES.has(dependencyName)) {
+    return buildCommandDisplay("brew", ["install", "--cask", PACKAGE_NAMES.brew[dependencyName]]);
+  }
+
+  if (manager === "choco") {
+    return buildCommandDisplay("choco", ["install", PACKAGE_NAMES.choco[dependencyName]]);
+  }
+
+  return buildCommandDisplay(manager, ["install", PACKAGE_NAMES[manager][dependencyName]]);
+}
+
+function buildGuidedInstallMessage(
+  dependencyName: DependencyName,
+  summary: string,
+  options: { requiredForFileType?: string } = {},
+): string {
+  const macCommand = createDisplayCommand("brew", dependencyName);
+  const ubuntuCommand = createDisplayCommand("apt-get", dependencyName);
+  const windowsCommand = createDisplayCommand("choco", dependencyName);
+  const requirement = options.requiredForFileType
+    ? ` to convert ${options.requiredForFileType} files`
+    : "";
+
+  return `${summary}${requirement}. On macOS: ${macCommand}, On Ubuntu: ${ubuntuCommand}, On Windows: ${windowsCommand}`;
+}
+
+function formatGhostscriptMissingMessage(extension: string): string {
+  const fileTypeLabel = (extension || "vector").replace(/^\./, "").toUpperCase();
+  return buildGuidedInstallMessage("ghostscript", `Ghostscript is required but is not installed`, {
+    requiredForFileType: fileTypeLabel,
+  });
+}
+
+function getLinuxInstallArgs(managerId: PackageManagerId, packageNames: string[]): string[] {
+  if (managerId === "pacman") {
+    return ["-Sy", "--noconfirm", ...packageNames];
+  }
+
+  if (managerId === "apk") {
+    return ["add", ...packageNames];
+  }
+
+  return ["install", "-y", ...packageNames];
+}
+
 async function getUnixPrivilegeContext(): Promise<UnixPrivilegeContext> {
   if (typeof process.getuid === "function" && process.getuid() === 0) {
     return {
@@ -302,6 +279,40 @@ function buildLinuxInstallCommands(
   return commands;
 }
 
+function buildBrewInstallCommands(dependencyNames: DependencyName[]): InstallCommandSpec[] {
+  const formulaDependencies = dependencyNames.filter(
+    (dependencyName) => !BREW_CASK_DEPENDENCIES.has(dependencyName),
+  );
+  const caskDependencies = dependencyNames.filter((dependencyName) =>
+    BREW_CASK_DEPENDENCIES.has(dependencyName),
+  );
+  const commands: InstallCommandSpec[] = [];
+
+  if (formulaDependencies.length > 0) {
+    commands.push(
+      createCommandSpec(
+        "Install missing document parser dependencies via Homebrew",
+        "brew",
+        ["install", ...getPackageNames("brew", formulaDependencies)],
+        { timeoutMs: INSTALL_COMMAND_TIMEOUT_MS },
+      ),
+    );
+  }
+
+  if (caskDependencies.length > 0) {
+    commands.push(
+      createCommandSpec(
+        "Install missing document parser dependencies via Homebrew Cask",
+        "brew",
+        ["install", "--cask", ...getPackageNames("brew", caskDependencies)],
+        { timeoutMs: INSTALL_COMMAND_TIMEOUT_MS },
+      ),
+    );
+  }
+
+  return commands;
+}
+
 function buildWingetCommands(dependencyNames: DependencyName[]): InstallCommandSpec[] {
   return dependencyNames.map((dependencyName) =>
     createCommandSpec(
@@ -320,6 +331,64 @@ function buildWingetCommands(dependencyNames: DependencyName[]): InstallCommandS
   );
 }
 
+const DEPENDENCY_METADATA: Record<
+  DependencyName,
+  {
+    label: string;
+    summary: string;
+    findCommand: () => Promise<string | undefined>;
+    getMissingMessage: (inspection?: InputInspection) => string;
+  }
+> = {
+  libreoffice: {
+    label: "LibreOffice",
+    summary:
+      "Needed for Office documents and spreadsheets such as DOCX, PPTX, XLSX, CSV, and similar formats.",
+    findCommand: () =>
+      findFirstAvailableCommand(
+        ["libreoffice", "soffice"],
+        process.platform === "darwin"
+          ? [
+              "/Applications/LibreOffice.app/Contents/MacOS/soffice",
+              "/Applications/LibreOffice.app/Contents/MacOS/libreoffice",
+            ]
+          : process.platform === "win32"
+            ? [
+                "C:\\Program Files\\LibreOffice\\program\\soffice.exe",
+                "C:\\Program Files\\LibreOffice\\program\\libreoffice.exe",
+                "C:\\Program Files (x86)\\LibreOffice\\program\\soffice.exe",
+                "C:\\Program Files (x86)\\LibreOffice\\program\\libreoffice.exe",
+              ]
+            : [],
+      ),
+    getMissingMessage: () =>
+      buildGuidedInstallMessage(
+        "libreoffice",
+        "LibreOffice is not installed. Please install LibreOffice to convert office documents",
+      ),
+  },
+  imagemagick: {
+    label: "ImageMagick",
+    summary:
+      "Needed for image inputs such as PNG, JPG, TIFF, WebP, SVG, and similar formats that must be converted before parsing.",
+    findCommand: () =>
+      findFirstAvailableCommand(process.platform === "win32" ? ["magick"] : ["magick", "convert"]),
+    getMissingMessage: () =>
+      buildGuidedInstallMessage(
+        "imagemagick",
+        "ImageMagick is not installed. Please install ImageMagick to convert images",
+      ),
+  },
+  ghostscript: {
+    label: "Ghostscript",
+    summary:
+      "Needed for vector image conversion paths such as SVG, EPS, PS, and AI when ImageMagick delegates rendering.",
+    findCommand: () => findFirstAvailableCommand(["gs", "gswin64c", "gswin32c"]),
+    getMissingMessage: (inspection) =>
+      formatGhostscriptMissingMessage(inspection?.extension || ".svg"),
+  },
+};
+
 export function getRelevantDependencyNames(inspection?: InputInspection): Set<DependencyName> {
   if (!inspection) {
     return new Set(DEPENDENCY_NAMES);
@@ -409,14 +478,7 @@ export async function buildInstallStrategies(
         label: "Homebrew",
         autoRunnable: brewAvailable,
         autoRunBlockedReason: brewAvailable ? undefined : "Homebrew was not detected on PATH.",
-        commands: [
-          createCommandSpec(
-            "Install missing document parser dependencies via Homebrew",
-            "brew",
-            ["install", ...getPackageNames("brew", missingNames)],
-            { timeoutMs: INSTALL_COMMAND_TIMEOUT_MS },
-          ),
-        ],
+        commands: buildBrewInstallCommands(missingNames),
       },
     ];
   }

package/extensions/docparser/doctor.ts

@@ -1,4 +1,8 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import {
+  BorderedLoader,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
 
 import { DOCTOR_COMMAND, DOCTOR_COMMAND_NAME, INSTALL_COMMAND_TIMEOUT_MS } from "./constants.ts";
 import {
@@ -14,8 +18,8 @@ import { resolveDocumentTarget } from "./input.ts";
 import type {
   DependencyDiagnosis,
   InputInspection,
+  InstallCommandSpec,
   InstallStrategy,
-  UiMessageLevel,
 } from "./types.ts";
 
 function normalizeDoctorArgument(input: string): string | undefined {
@@ -38,11 +42,9 @@ function formatDoctorReport(options: {
   diagnoses: DependencyDiagnosis[];
   strategies: InstallStrategy[];
   installSummary?: string[];
-}): { text: string; level: UiMessageLevel } {
+}): string {
   const missing = options.diagnoses.filter((diagnosis) => !diagnosis.installed);
   const relevantMissing = missing.filter((diagnosis) => diagnosis.relevant);
-  const level: UiMessageLevel =
-    relevantMissing.length > 0 ? "error" : missing.length > 0 ? "warning" : "info";
   const lines = ["docparser doctor", `Platform: ${getPlatformLabel()}`];
 
   if (options.sourcePath) {
@@ -64,6 +66,14 @@ function formatDoctorReport(options: {
     lines.push(
       "This input type does not require extra host conversion packages for normal parsing.",
     );
+  } else if (relevantMissing.length > 0) {
+    lines.push("Action needed: install the missing packages listed below.");
+  } else if (missing.length > 0) {
+    lines.push(
+      "Optional host packages are missing. Install them if you plan to parse inputs that need them.",
+    );
+  } else {
+    lines.push("All relevant host dependencies are installed.");
   }
 
   lines.push("Dependency status:");
@@ -119,10 +129,7 @@ function formatDoctorReport(options: {
     }
   }
 
-  return {
-    text: lines.join("\n"),
-    level,
-  };
+  return lines.join("\n");
 }
 
 async function collectDoctorState(inspection?: InputInspection): Promise<{
@@ -163,6 +170,77 @@ async function selectInstallStrategy(
   return strategies.find((strategy) => strategy.label === selectedLabel);
 }
 
+async function runInstallCommands(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  commands: InstallCommandSpec[],
+): Promise<string[]> {
+  const runInstallLoop = async () => {
+    const installSummary: string[] = [];
+
+    for (const command of commands) {
+      const result = await pi.exec(command.command, command.args, {
+        timeout: command.timeoutMs ?? INSTALL_COMMAND_TIMEOUT_MS,
+      });
+      const success = result.code === 0 && !result.killed;
+
+      installSummary.push(
+        `${command.description}: ${success ? "ok" : `failed (exit ${result.code}${result.killed ? ", killed" : ""})`}`,
+      );
+
+      if (!success) {
+        const outputSummary = summarizeInstallOutput(result.stdout, result.stderr);
+        if (outputSummary) {
+          installSummary.push(`Command output:\n${outputSummary}`);
+        }
+      }
+    }
+
+    return installSummary;
+  };
+
+  let ranCustomUi = false;
+  let installSummary: string[] | undefined;
+  let installError: unknown;
+
+  await ctx.ui.custom<boolean | undefined>((tui, theme, _kb, done) => {
+    ranCustomUi = true;
+
+    const loader = new BorderedLoader(
+      tui,
+      theme,
+      "Installing missing packages. Please do not quit pi until this finishes.",
+      { cancellable: false },
+    );
+
+    runInstallLoop()
+      .then((summary) => {
+        installSummary = summary;
+        done(true);
+      })
+      .catch((error) => {
+        installError = error;
+        done(false);
+      });
+
+    return loader;
+  });
+
+  if (!ranCustomUi) {
+    ctx.ui.notify(
+      "Installing missing packages. This can take a few minutes. Please wait for the final doctor report.",
+      "info",
+    );
+    return runInstallLoop();
+  }
+
+  if (installError) {
+    throw installError;
+  }
+
+  return installSummary ?? [];
+}
+
 export function registerDoctorCommand(pi: ExtensionAPI) {
   pi.registerCommand(DOCTOR_COMMAND_NAME, {
     description:
@@ -188,6 +266,8 @@ export function registerDoctorCommand(pi: ExtensionAPI) {
         return;
       }
 
+      await ctx.waitForIdle();
+
       try {
         let target: Awaited<ReturnType<typeof resolveDocumentTarget>> | undefined;
         try {
@@ -207,7 +287,7 @@ export function registerDoctorCommand(pi: ExtensionAPI) {
           diagnoses: initialState.diagnoses,
           strategies: initialState.strategies,
         });
-        ctx.ui.notify(initialReport.text, initialReport.level);
+        ctx.ui.notify(initialReport, "info");
 
         if (
           initialState.missingDependencies.length === 0 ||
@@ -250,25 +330,7 @@ export function registerDoctorCommand(pi: ExtensionAPI) {
           return;
         }
 
-        const installSummary: string[] = [];
-        for (const command of selectedStrategy.commands) {
-          ctx.ui.notify(`Running: ${command.display}`, "info");
-          const result = await pi.exec(command.command, command.args, {
-            timeout: command.timeoutMs ?? INSTALL_COMMAND_TIMEOUT_MS,
-          });
-          const success = result.code === 0 && !result.killed;
-
-          installSummary.push(
-            `${command.description}: ${success ? "ok" : `failed (exit ${result.code}${result.killed ? ", killed" : ""})`}`,
-          );
-
-          if (!success) {
-            const outputSummary = summarizeInstallOutput(result.stdout, result.stderr);
-            if (outputSummary) {
-              installSummary.push(`Command output:\n${outputSummary}`);
-            }
-          }
-        }
+        const installSummary = await runInstallCommands(pi, ctx, selectedStrategy.commands);
 
         const finalState = await collectDoctorState(target?.inspection);
         const finalReport = formatDoctorReport({
@@ -279,7 +341,7 @@ export function registerDoctorCommand(pi: ExtensionAPI) {
           strategies: finalState.strategies,
           installSummary,
         });
-        ctx.ui.notify(finalReport.text, finalReport.level);
+        ctx.ui.notify(finalReport, "info");
       } catch (error) {
         ctx.ui.notify(
           `docparser doctor failed: ${error instanceof Error ? error.message : String(error)}`,

package/extensions/docparser/types.ts

@@ -31,7 +31,6 @@ export type PackageManagerId =
   | "apk"
   | "winget"
   | "choco";
-export type UiMessageLevel = "info" | "warning" | "error";
 
 export interface InputInspection {
   extension: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-docparser",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pi package that adds a document_parse tool and companion skill for parsing PDFs, Office documents, spreadsheets, and images with LiteParse.",
   "keywords": [
     "document-parse",
@@ -13,6 +13,10 @@
   ],
   "homepage": "https://maximilian-schwarzmueller.com",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxedapps/pi-docparser.git"
+  },
   "files": [
     "assets",
     "extensions",