Merge pull request #204 from proofgeist/feature/fix-addon-install-flow

Fix addon install flow for existing projects

Author: eluce2

.changeset/clear-lions-think.md

@@ -0,0 +1,5 @@
+---
+"@proofkit/webviewer": patch
+---
+
+Document the `proofkit add addon webviewer` command in the WebViewer skill and setup docs.

.changeset/fair-poems-care.md

@@ -0,0 +1,5 @@
+---
+"@proofkit/cli": patch
+---
+
+Fix `proofkit add addon` so it works outside an existing ProofKit project.

apps/docs/content/docs/cli/webviewer/getting-started.mdx

@@ -15,7 +15,7 @@ Creating a ProofKit project for a FileMaker WebViewer is extremely similar to th
 
 ## Prep your FileMaker file
 
-- Install the ProofKit WebViewer add-on into the file you want to target.
+- Install the ProofKit WebViewer add-on into the file you want to target. If you already have a ProofKit project, run `proofkit add addon webviewer` to copy the local add-on files, then install the add-on into the FileMaker file.
 - Make sure the file has the scripts needed by your WebViewer workflow, such as `Launch Web Viewer for Dev` and `UploadWebviewerWidget`.
 - If you want local typegen without a hosted server, start the FM MCP bridge and keep a connected FileMaker file open.
 

apps/docs/content/docs/webviewer/index.mdx

@@ -19,14 +19,16 @@ For web-based applications where you're looking to interact with the Data API us
 
 We strongly recommend using the [ProofKit CLI](/docs/cli) to setup your project. It will also walk you through a FileMaker add-on that installs the neccesary layouts, scripts and custom functions to get you started.
 
+If you already have a ProofKit WebViewer project and need to install or update the FileMaker add-on manually, run `proofkit add addon webviewer` from the project root. That copies the local add-on files; you still need to install the add-on into the FileMaker file.
+
 <Accordions type="single">
   <Accordion title="Manual Installation">
 
 {" "}
 <Callout type="warn">
   This demo file is a very simplified example. To see more features, use the
-  [ProofKit CLI](/docs/cli) to build a new app and follow the instructions to
-  install the FileMaker addon.
+  [ProofKit CLI](/docs/cli) to build a new app or run `proofkit add addon webviewer`
+  in an existing ProofKit project, then install the FileMaker add-on.
 </Callout>
 
 Use your preferred package manager to install the package.

packages/cli/src/cli/add/addon.ts

@@ -3,8 +3,7 @@ import { select } from "~/cli/prompts.js";
 import { debugOption, nonInteractiveOption } from "~/globalOptions.js";
 import { installFmAddonExplicitly } from "~/installers/install-fm-addon.js";
 import { initProgramState, isNonInteractiveMode } from "~/state.js";
-import { getSettings } from "~/utils/parseSettings.js";
-import { abortIfCancel, ensureProofKitProject } from "../utils.js";
+import { abortIfCancel } from "../utils.js";
 
 type AddonTarget = "webviewer" | "auth";
 
@@ -29,18 +28,8 @@ async function resolveAddonTarget(name?: string): Promise<AddonTarget> {
 }
 
 export async function runAddAddonAction(targetName?: string) {
-  ensureProofKitProject({ commandName: "add addon" });
-  const settings = getSettings();
   const target = await resolveAddonTarget(targetName);
 
-  if (target === "webviewer" && settings.appType !== "webviewer") {
-    throw new Error("The WebViewer add-on can only be added from a WebViewer ProofKit project.");
-  }
-
-  if (target === "auth" && settings.appType !== "browser") {
-    throw new Error("The auth add-on can only be added from a browser ProofKit project.");
-  }
-
   await installFmAddonExplicitly({ addonName: target === "webviewer" ? "wv" : "auth" });
 }
 

packages/cli/src/installers/install-fm-addon.ts

@@ -211,14 +211,16 @@ export async function inspectFmAddon(
 export function getFmAddonInstallInstructions(addonName: FmAddonName) {
   const addonDisplayName = getAddonDisplayName(addonName);
   const installCommand = getAddonInstallCommand(addonName);
+  const removeOldStep = `If your FileMaker file already has an older ${addonDisplayName} add-on installed, remove that old add-on first`;
 
   return {
     addonDisplayName,
     installCommand,
     docsUrl: addonName === "auth" ? "https://proofkit.dev/auth/fm-addon" : "https://proofkit.dev/webviewer",
     steps: [
       `Run \`${installCommand}\` to install or update the local add-on files`,
-      "Restart FileMaker Pro (if it's currently running)",
+      "Restart FileMaker Pro so the new local add-on files appear",
+      removeOldStep,
       `Open your FileMaker file, go to layout mode, and install the ${addonDisplayName} add-on to the file`,
     ],
   };
@@ -256,8 +258,9 @@ export async function installFmAddonExplicitly({ addonName }: { addonName: FmAdd
     );
   }
   const steps = [
-    "Restart FileMaker Pro (if it's currently running)",
-    `Open your FileMaker file, go to layout mode, and install the ${addonDisplayName} addon to the file`,
+    "Restart FileMaker Pro so the new local add-on files appear",
+    `If your FileMaker file already has an older ${addonDisplayName} add-on installed, remove that old add-on first`,
+    `Open your FileMaker file, go to layout mode, and install the ${addonDisplayName} add-on to the file`,
   ];
   steps.forEach((step, index) => {
     console.log(`${index + 1}. ${step}`);

packages/cli/tests/cli.test.ts

@@ -137,13 +137,6 @@ describe("proofkit CLI", () => {
   it("supports `proofkit add addon webviewer`", async () => {
     const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "proofkit-new-cli-addon-project-"));
     const addonModulesDir = await fs.mkdtemp(path.join(os.tmpdir(), "proofkit-new-cli-addon-modules-"));
-    await fs.writeJson(path.join(cwd, "proofkit.json"), {
-      appType: "webviewer",
-      ui: "shadcn",
-      dataSources: [],
-      replacedMainPage: false,
-      registryTemplates: [],
-    });
 
     const result = spawnSync("node", [distEntry, "add", "addon", "webviewer", "--non-interactive"], {
       cwd,

packages/cli/tests/install-fm-addon.test.ts

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import { describe, expect, it } from "vitest";
-import { compareAddonVersions, inspectFmAddon } from "~/installers/install-fm-addon.js";
+import { compareAddonVersions, getFmAddonInstallInstructions, inspectFmAddon } from "~/installers/install-fm-addon.js";
 import { getWebViewerAddonMessages } from "~/installers/proofkit-webviewer.js";
 
 async function writeAddonVersion(dir: string, version: string) {
@@ -112,3 +112,12 @@ describe("getWebViewerAddonMessages", () => {
     expect(messages.nextSteps).toEqual(["proofkit add addon webviewer"]);
   });
 });
+
+describe("getFmAddonInstallInstructions", () => {
+  it("includes restart and old add-on removal guidance", () => {
+    const instructions = getFmAddonInstallInstructions("wv");
+
+    expect(instructions.steps).toContain("Restart FileMaker Pro so the new local add-on files appear");
+    expect(instructions.steps.join("\n")).toContain("remove that old add-on first");
+  });
+});

packages/webviewer/skills/webviewer-integration/SKILL.md

@@ -15,8 +15,13 @@ sources:
 
 ## Setup
 
+This package assumes the user has already added specific layouts, scripts, etc into their FileMaker file. This is accomplished using a FileMaker add-on, downloaded during the setup process if the project was created using @proofkit/cli, but the user must still manually install the add-on in their FileMaker file.
+To download the latest version of the add-on to the user's computer, run `npx -y @proofkit/cli@beta add addon webviewer` in any directory.
+
 Install the package and set the webviewer name before calling any scripts.
 
+
+
 ```ts
 import { fmFetch, globalSettings } from "@proofkit/webviewer";