@vellumai/assistant 0.6.5 → 0.7.0

package/src/runtime/routes/app-management-routes.ts

@@ -1,11 +1,6 @@
 /**
- * HTTP route definitions for app CRUD, bundling, sharing, versioning,
+ * Route handlers for app CRUD, bundling, sharing, versioning,
  * gallery, and signing operations.
- *
- * Business logic is extracted from the handlers in
- * `daemon/handlers/apps.ts`, `daemon/handlers/publish.ts`,
- * `daemon/handlers/signing.ts`, and `daemon/handlers/open-bundle-handler.ts`
- * so that the same operations are available over HTTP.
  */
 import {
   existsSync,
@@ -51,8 +46,8 @@ import {
 import { createSharedAppLink } from "../../memory/shared-app-links-store.js";
 import { computeContentId } from "../../util/content-id.js";
 import { getLogger } from "../../util/logger.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("app-management-routes");
 
@@ -108,18 +103,20 @@ function getAppDataResult(
     case "query":
       return queryAppRecords(appId);
     case "create":
-      if (!data) throw new Error("data is required for create");
+      if (!data) throw new BadRequestError("data is required for create");
       return createAppRecord(appId, data);
     case "update":
-      if (!recordId) throw new Error("recordId is required for update");
-      if (!data) throw new Error("data is required for update");
+      if (!recordId)
+        throw new BadRequestError("recordId is required for update");
+      if (!data) throw new BadRequestError("data is required for update");
       return updateAppRecord(appId, recordId, data);
     case "delete":
-      if (!recordId) throw new Error("recordId is required for delete");
+      if (!recordId)
+        throw new BadRequestError("recordId is required for delete");
       deleteAppRecord(appId, recordId);
       return null;
     default:
-      throw new Error(`Unknown app data method: ${method}`);
+      throw new BadRequestError(`Unknown app data method: ${method}`);
   }
 }
 
@@ -185,7 +182,6 @@ function listSharedApps(): Array<Record<string, unknown>> {
     }
   }
 
-  // Detect update availability for non-forked shared apps.
   const contentIdVersions = new Map<string, string[]>();
   for (const app of apps) {
     if (app.contentId && !app.forked) {
@@ -355,675 +351,483 @@ async function openBundle(filePath: string): Promise<Record<string, unknown>> {
 }
 
 // ---------------------------------------------------------------------------
-// Route definitions
+// Route handlers
 // ---------------------------------------------------------------------------
 
-export function appManagementRouteDefinitions(): RouteDefinition[] {
-  return [
-    // -----------------------------------------------------------------------
-    // Literal path routes MUST come before parameterized `apps/:id/*` routes
-    // to prevent the `:id` param from capturing "shared", "fork", etc.
-    // -----------------------------------------------------------------------
-
-    // --- App list ---
-
-    {
-      endpoint: "apps",
-      method: "GET",
-      policyKey: "apps",
-      summary: "List apps",
-      description: "Return all locally installed apps.",
-      tags: ["apps"],
-      responseBody: z.object({
-        apps: z.array(z.unknown()).describe("Array of app summary objects"),
-      }),
-      handler: () => {
-        try {
-          const apps = listAppsFiltered();
-          return Response.json({ apps });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to list apps");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to list apps: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+function handleListApps() {
+  return { apps: listAppsFiltered() };
+}
 
-    // --- Open bundle (no :id param) ---
-
-    {
-      endpoint: "apps/open-bundle",
-      method: "POST",
-      policyKey: "apps/open-bundle",
-      summary: "Open a .vbundle file",
-      description:
-        "Scan and validate a .vbundle file from disk and return its manifest.",
-      tags: ["apps"],
-      requestBody: z.object({
-        filePath: z.string().describe("Absolute path to the .vbundle file"),
-      }),
-      handler: async ({ req }) => {
-        try {
-          const body = (await req.json()) as { filePath?: string };
-          if (!body.filePath) {
-            return httpError("BAD_REQUEST", "filePath is required", 400);
-          }
-          const result = await openBundle(body.filePath);
-          return Response.json(result);
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to open bundle");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to open bundle: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleOpenBundle({ body }: RouteHandlerArgs) {
+  if (!body?.filePath) {
+    throw new BadRequestError("filePath is required");
+  }
+  return openBundle(body.filePath as string);
+}
 
-    // --- Shared apps list (literal "apps/shared" GET) ---
-    // NOTE: The existing appRouteDefinitions() already handles
-    // apps/shared/:token (GET/DELETE) — this new route uses a different
-    // method (GET with no sub-path param) so there is no conflict.
-
-    {
-      endpoint: "apps/shared",
-      method: "GET",
-      policyKey: "apps/shared-list",
-      summary: "List shared apps",
-      description: "Return all apps available via cloud share links.",
-      tags: ["apps"],
-      responseBody: z.object({
-        apps: z.array(z.unknown()).describe("Array of shared app objects"),
-      }),
-      handler: () => {
-        try {
-          const apps = listSharedApps();
-          return Response.json({ apps });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to list shared apps");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to list shared apps: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+function handleListSharedApps() {
+  return { apps: listSharedApps() };
+}
 
-    // --- Fork shared app ---
-
-    {
-      endpoint: "apps/fork",
-      method: "POST",
-      policyKey: "apps/fork",
-      summary: "Fork a shared app",
-      description: "Create a local copy of a shared app by its UUID.",
-      tags: ["apps"],
-      requestBody: z.object({
-        uuid: z.string().describe("UUID of the shared app to fork"),
-      }),
-      handler: async ({ req }) => {
-        try {
-          const body = (await req.json()) as { uuid?: string };
-          if (!body.uuid) {
-            return httpError("BAD_REQUEST", "uuid is required", 400);
-          }
-          const result = forkSharedApp(body.uuid);
-          if (!result.success) {
-            return Response.json(result, { status: 400 });
-          }
-          return Response.json(result);
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to fork shared app");
-          return Response.json(
-            { success: false, error: message },
-            { status: 500 },
-          );
-        }
-      },
-    },
+function handleForkSharedApp({ body }: RouteHandlerArgs) {
+  if (!body?.uuid) {
+    throw new BadRequestError("uuid is required");
+  }
+  const result = forkSharedApp(body.uuid as string);
+  if (!result.success) {
+    throw new BadRequestError(result.error);
+  }
+  return result;
+}
 
-    // --- Gallery ---
-
-    {
-      endpoint: "apps/gallery/install",
-      method: "POST",
-      policyKey: "apps/gallery/install",
-      summary: "Install a gallery app",
-      description: "Install an app from the built-in gallery by its ID.",
-      tags: ["apps"],
-      requestBody: z.object({
-        galleryAppId: z.string(),
-      }),
-      handler: async ({ req }) => {
-        try {
-          const body = (await req.json()) as { galleryAppId?: string };
-          if (!body.galleryAppId) {
-            return httpError("BAD_REQUEST", "galleryAppId is required", 400);
-          }
-          const result = await installGalleryApp(body.galleryAppId);
-          if (!result.success) {
-            return Response.json(result, { status: 400 });
-          }
-          return Response.json(result);
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to install gallery app");
-          return Response.json(
-            { success: false, error: message },
-            { status: 500 },
-          );
-        }
-      },
-    },
+async function handleInstallGalleryApp({ body }: RouteHandlerArgs) {
+  if (!body?.galleryAppId) {
+    throw new BadRequestError("galleryAppId is required");
+  }
+  const result = await installGalleryApp(body.galleryAppId as string);
+  if (!result.success) {
+    throw new BadRequestError(result.error);
+  }
+  return result;
+}
 
-    {
-      endpoint: "apps/gallery",
-      method: "GET",
-      policyKey: "apps/gallery",
-      summary: "List gallery apps",
-      description: "Return the built-in app gallery catalog.",
-      tags: ["apps"],
-      responseBody: z.object({
-        gallery: z.array(z.unknown()).describe("Gallery app entries"),
-      }),
-      handler: () => {
-        return Response.json({ gallery: defaultGallery });
-      },
-    },
+function handleListGallery() {
+  return { gallery: defaultGallery };
+}
 
-    // --- Signing ---
-
-    {
-      endpoint: "apps/sign-bundle",
-      method: "POST",
-      policyKey: "apps/sign-bundle",
-      summary: "Sign an app bundle",
-      description:
-        "Return a signing payload or complete the signing step when signature fields are provided.",
-      tags: ["apps"],
-      requestBody: z.object({
-        payload: z.string().describe("Canonical JSON payload to sign"),
-        signature: z
-          .string()
-          .describe("Ed25519 signature (optional, completes signing)")
-          .optional(),
-        keyId: z.string().optional(),
-        publicKey: z.string().optional(),
-      }),
-      handler: async ({ req }) => {
-        try {
-          const body = (await req.json()) as {
-            payload?: string;
-            signature?: string;
-            keyId?: string;
-            publicKey?: string;
-          };
-          if (!body.payload) {
-            return httpError("BAD_REQUEST", "payload is required", 400);
-          }
-
-          // When all signature fields are present, complete the signing step.
-          if (body.signature && body.keyId && body.publicKey) {
-            // Extract content_hashes from the canonical payload the client signed.
-            let contentHashes: Record<string, string> = {};
-            try {
-              const parsed = JSON.parse(body.payload) as {
-                content_hashes?: Record<string, string>;
-              };
-              contentHashes = parsed.content_hashes ?? {};
-            } catch {
-              return httpError("BAD_REQUEST", "payload is not valid JSON", 400);
-            }
-
-            const signatureJson: SignatureJson = {
-              algorithm: "ed25519",
-              signer: {
-                key_id: body.keyId,
-                display_name: "HTTP Signer",
-              },
-              content_hashes: contentHashes,
-              signature: body.signature,
-            };
-            return Response.json({ signed: true, signatureJson });
-          }
-
-          // Otherwise return the payload for the client to sign.
-          return Response.json({
-            payload: body.payload,
-            message:
-              "Sign the payload with your private key and include signature, keyId, and publicKey in the request body.",
-          });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to process sign-bundle request");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to process sign-bundle: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+function handleSignBundle({ body }: RouteHandlerArgs) {
+  if (!body?.payload) {
+    throw new BadRequestError("payload is required");
+  }
 
-    {
-      endpoint: "apps/signing-identity",
-      method: "GET",
-      policyKey: "apps/signing-identity",
-      summary: "Get signing identity",
-      description:
-        "Return signing identity info. Signing is managed client-side over HTTP.",
-      tags: ["apps"],
-      handler: () => {
-        // Signing identity is a client-side concept. Over HTTP, the
-        // client already holds its own keys. Return a placeholder
-        // indicating that signing is client-managed.
-        return Response.json({
-          message:
-            "Signing identity is managed client-side. Use your local keychain to obtain keyId and publicKey.",
-        });
+  const payload = body.payload as string;
+  const signature = body.signature as string | undefined;
+  const keyId = body.keyId as string | undefined;
+  const publicKey = body.publicKey as string | undefined;
+
+  if (signature && keyId && publicKey) {
+    let contentHashes: Record<string, string> = {};
+    try {
+      const parsed = JSON.parse(payload) as {
+        content_hashes?: Record<string, string>;
+      };
+      contentHashes = parsed.content_hashes ?? {};
+    } catch {
+      throw new BadRequestError("payload is not valid JSON");
+    }
+
+    const signatureJson: SignatureJson = {
+      algorithm: "ed25519",
+      signer: {
+        key_id: keyId,
+        display_name: "HTTP Signer",
       },
-    },
+      content_hashes: contentHashes,
+      signature,
+    };
+    return { signed: true, signatureJson };
+  }
 
-    // -----------------------------------------------------------------------
-    // Parameterized `apps/:id/*` routes — must follow all literal routes.
-    // -----------------------------------------------------------------------
+  return {
+    payload,
+    message:
+      "Sign the payload with your private key and include signature, keyId, and publicKey in the request body.",
+  };
+}
 
-    // --- App data ---
+function handleSigningIdentity() {
+  return {
+    message:
+      "Signing identity is managed client-side. Use your local keychain to obtain keyId and publicKey.",
+  };
+}
 
-    {
-      endpoint: "apps/:id/data",
-      method: "GET",
-      policyKey: "apps/data",
-      summary: "Query app data",
-      description: "Read records from an app's local data store.",
-      tags: ["apps"],
-      handler: ({ params, url }) => {
-        try {
-          const method = url.searchParams.get("method") ?? "query";
-          if (method !== "query") {
-            return httpError(
-              "BAD_REQUEST",
-              "GET app-data only supports method=query; use POST for mutations",
-              400,
-            );
-          }
-          const result = getAppDataResult(method, params.id);
-          return Response.json({ success: true, result });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error(
-            { err, appId: params.id },
-            "Error handling app data request",
-          );
-          return Response.json(
-            { success: false, error: message },
-            { status: 400 },
-          );
-        }
-      },
-    },
+function handleQueryAppData({ pathParams, queryParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const method = queryParams?.method ?? "query";
+  if (method !== "query") {
+    throw new BadRequestError(
+      "GET app-data only supports method=query; use POST for mutations",
+    );
+  }
+  const result = getAppDataResult(method, appId);
+  return { success: true, result };
+}
 
-    {
-      endpoint: "apps/:id/data",
-      method: "POST",
-      policyKey: "apps/data",
-      summary: "Mutate app data",
-      description:
-        "Create, update, or delete records in an app's local data store.",
-      tags: ["apps"],
-      requestBody: z.object({
-        method: z.string().describe("'create', 'update', or 'delete'"),
-        recordId: z.string(),
-        data: z.object({}).passthrough(),
-      }),
-      handler: async ({ params, req }) => {
-        try {
-          const body = (await req.json()) as {
-            method?: string;
-            recordId?: string;
-            data?: Record<string, unknown>;
-          };
-          const method = body.method ?? "create";
-          const result = getAppDataResult(
-            method,
-            params.id,
-            body.recordId,
-            body.data,
-          );
-          return Response.json({ success: true, result });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error(
-            { err, appId: params.id },
-            "Error handling app data request",
-          );
-          return Response.json(
-            { success: false, error: message },
-            { status: 400 },
-          );
-        }
-      },
-    },
+function handleMutateAppData({ pathParams, body }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const method = (body?.method as string) ?? "create";
+  const result = getAppDataResult(
+    method,
+    appId,
+    body?.recordId as string | undefined,
+    body?.data as Record<string, unknown> | undefined,
+  );
+  return { success: true, result };
+}
 
-    // --- App open ---
-
-    {
-      endpoint: "apps/:id/open",
-      method: "POST",
-      policyKey: "apps/open",
-      summary: "Open an app",
-      description:
-        "Compile (if needed) and return the app's HTML for rendering.",
-      tags: ["apps"],
-      responseBody: z.object({
-        appId: z.string(),
-        dirName: z.string(),
-        name: z.string(),
-        html: z.string(),
-      }),
-      handler: async ({ params }) => {
-        try {
-          const appId = params.id;
-          const app = getApp(appId);
-          if (!app) {
-            return httpError("NOT_FOUND", `App not found: ${appId}`, 404);
-          }
-
-          if (isMultifileApp(app)) {
-            const appDir = getAppDirPath(appId);
-            const distIndex = join(appDir, "dist", "index.html");
-            if (!existsSync(distIndex)) {
-              const result = await compileApp(appDir);
-              if (!result.ok) {
-                log.warn(
-                  { appId, errors: result.errors },
-                  "Auto-compile failed on app open",
-                );
-              }
-            }
-          }
-          const html = resolveEffectiveAppHtml(app);
-
-          const { dirName } = resolveAppDir(app.id);
-          return Response.json({
-            appId: app.id,
-            dirName,
-            name: app.name,
-            html,
-          });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error(
-            { err, appId: params.id },
-            "Failed to handle app open request",
-          );
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to open app: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleOpenApp({ pathParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const app = getApp(appId);
+  if (!app) {
+    throw new NotFoundError(`App not found: ${appId}`);
+  }
 
-    // --- App delete ---
+  if (isMultifileApp(app)) {
+    const appDir = getAppDirPath(appId);
+    const distIndex = join(appDir, "dist", "index.html");
+    if (!existsSync(distIndex)) {
+      const result = await compileApp(appDir);
+      if (!result.ok) {
+        log.warn(
+          { appId, errors: result.errors },
+          "Auto-compile failed on app open",
+        );
+      }
+    }
+  }
+  const html = resolveEffectiveAppHtml(app);
+  const { dirName } = resolveAppDir(app.id);
+  return { appId: app.id, dirName, name: app.name, html };
+}
 
-    {
-      endpoint: "apps/:id/delete",
-      method: "POST",
-      policyKey: "apps/delete",
-      summary: "Delete an app",
-      description: "Permanently remove an app and its data.",
-      tags: ["apps"],
-      handler: ({ params }) => {
-        try {
-          deleteApp(params.id);
-          return Response.json({ success: true });
-        } catch (err) {
-          log.error({ err, appId: params.id }, "Failed to delete app");
-          return Response.json({ success: false }, { status: 500 });
-        }
-      },
-    },
+function handleDeleteApp({ pathParams }: RouteHandlerArgs) {
+  deleteApp(pathParams?.id as string);
+  return { success: true };
+}
 
-    // --- Preview ---
+function handleGetPreview({ pathParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const preview = getAppPreview(appId);
+  return { appId, preview: preview ?? null };
+}
 
-    {
-      endpoint: "apps/:id/preview",
-      method: "GET",
-      policyKey: "apps/preview",
-      summary: "Get app preview",
-      description: "Return the preview image or HTML for an app.",
-      tags: ["apps"],
-      handler: ({ params }) => {
-        try {
-          const preview = getAppPreview(params.id);
-          return Response.json({
-            appId: params.id,
-            preview: preview ?? null,
-          });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to get app preview");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to get app preview: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+function handleUpdatePreview({ pathParams, body }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  if (!body?.preview) {
+    throw new BadRequestError("preview is required");
+  }
+  updateApp(appId, { preview: body.preview as string });
+  return { success: true, appId };
+}
 
-    {
-      endpoint: "apps/:id/preview",
-      method: "PUT",
-      policyKey: "apps/preview",
-      summary: "Update app preview",
-      description: "Set a new preview image or HTML for an app.",
-      tags: ["apps"],
-      requestBody: z.object({
-        preview: z.string().describe("Base64-encoded image or HTML string"),
-      }),
-      handler: async ({ params, req }) => {
-        try {
-          const body = (await req.json()) as { preview?: string };
-          if (!body.preview) {
-            return httpError("BAD_REQUEST", "preview is required", 400);
-          }
-          updateApp(params.id, { preview: body.preview });
-          return Response.json({ success: true, appId: params.id });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err }, "Failed to update app preview");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to update app preview: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleGetHistory({
+  pathParams,
+  queryParams,
+}: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const limit = queryParams?.limit ? Number(queryParams.limit) : undefined;
+  const versions = await getAppHistory(appId, limit);
+  return { appId, versions };
+}
 
-    // --- History / Diff / Restore ---
-
-    {
-      endpoint: "apps/:id/history",
-      method: "GET",
-      policyKey: "apps/history",
-      summary: "Get app version history",
-      description: "Return the git commit history of an app.",
-      tags: ["apps"],
-      responseBody: z.object({
-        appId: z.string(),
-        versions: z.array(z.unknown()),
-      }),
-      handler: async ({ params, url }) => {
-        try {
-          const limit = url.searchParams.get("limit")
-            ? Number(url.searchParams.get("limit"))
-            : undefined;
-          const versions = await getAppHistory(params.id, limit);
-          return Response.json({ appId: params.id, versions });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to get app history");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to get app history: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleGetDiff({ pathParams, queryParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const fromCommit = queryParams?.fromCommit;
+  if (!fromCommit) {
+    throw new BadRequestError("fromCommit query parameter is required");
+  }
+  const toCommit = queryParams?.toCommit;
+  const diff = await getAppDiff(appId, fromCommit, toCommit);
+  return { appId, diff };
+}
 
-    {
-      endpoint: "apps/:id/diff",
-      method: "GET",
-      policyKey: "apps/diff",
-      summary: "Get app diff",
-      description: "Return a git diff between two commits for an app.",
-      tags: ["apps"],
-      handler: async ({ params, url }) => {
-        try {
-          const fromCommit = url.searchParams.get("fromCommit");
-          if (!fromCommit) {
-            return httpError(
-              "BAD_REQUEST",
-              "fromCommit query parameter is required",
-              400,
-            );
-          }
-          const toCommit = url.searchParams.get("toCommit") ?? undefined;
-          const diff = await getAppDiff(params.id, fromCommit, toCommit);
-          return Response.json({ appId: params.id, diff });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to get app diff");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to get app diff: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleRestore({ pathParams, body }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  if (!body?.commitHash) {
+    throw new BadRequestError("commitHash is required");
+  }
+  await restoreAppVersion(appId, body.commitHash as string);
+  return { success: true };
+}
 
-    {
-      endpoint: "apps/:id/restore",
-      method: "POST",
-      policyKey: "apps/restore",
-      summary: "Restore app version",
-      description: "Restore an app to a previous git commit.",
-      tags: ["apps"],
-      requestBody: z.object({
-        commitHash: z.string(),
-      }),
-      handler: async ({ params, req }) => {
-        try {
-          const body = (await req.json()) as { commitHash?: string };
-          if (!body.commitHash) {
-            return httpError("BAD_REQUEST", "commitHash is required", 400);
-          }
-          await restoreAppVersion(params.id, body.commitHash);
-          return Response.json({ success: true });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to restore app version");
-          return Response.json(
-            { success: false, error: message },
-            { status: 500 },
-          );
-        }
-      },
-    },
+async function handleBundle({ pathParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const result = await packageApp(appId);
+  return {
+    type: "bundle_app_response",
+    bundlePath: result.bundlePath,
+    iconImageBase64: result.iconImageBase64,
+    manifest: result.manifest,
+  };
+}
 
-    // --- Bundle ---
-
-    {
-      endpoint: "apps/:id/bundle",
-      method: "POST",
-      policyKey: "apps/bundle",
-      summary: "Bundle an app",
-      description: "Package an app into a distributable .vbundle archive.",
-      tags: ["apps"],
-      responseBody: z.object({
-        type: z.string(),
-        bundlePath: z.string(),
-        iconImageBase64: z.string(),
-        manifest: z.object({}).passthrough(),
-      }),
-      handler: async ({ params }) => {
-        try {
-          const result = await packageApp(params.id);
-          return Response.json({
-            type: "bundle_app_response",
-            bundlePath: result.bundlePath,
-            iconImageBase64: result.iconImageBase64,
-            manifest: result.manifest,
-          });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to bundle app");
-          return httpError(
-            "INTERNAL_ERROR",
-            `Failed to bundle app: ${message}`,
-            500,
-          );
-        }
-      },
-    },
+async function handleShareCloud({ pathParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id as string;
+  const result = await packageApp(appId);
+  const bundleData = readFileSync(result.bundlePath);
+  const { shareToken } = createSharedAppLink(bundleData, result.manifest);
+  const shareUrl = `/v1/apps/shared/${shareToken}`;
+  return { success: true, shareToken, shareUrl };
+}
 
-    // --- Share to cloud ---
-
-    {
-      endpoint: "apps/:id/share-cloud",
-      method: "POST",
-      policyKey: "apps/share-cloud",
-      summary: "Share app to cloud",
-      description: "Package and upload an app to the cloud share service.",
-      tags: ["apps"],
-      responseBody: z.object({
-        success: z.boolean(),
-        shareToken: z.string(),
-        shareUrl: z.string(),
-      }),
-      handler: async ({ params }) => {
-        try {
-          // Package without signing callback (HTTP clients handle signing
-          // separately or skip it). HTTP callers can use the sign-bundle
-          // endpoint independently if needed.
-          const result = await packageApp(params.id);
-          const bundleData = readFileSync(result.bundlePath);
-          const { shareToken } = createSharedAppLink(
-            bundleData,
-            result.manifest,
-          );
-
-          const shareUrl = `/v1/apps/shared/${shareToken}`;
-
-          return Response.json({
-            success: true,
-            shareToken,
-            shareUrl,
-          });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, appId: params.id }, "Failed to share app to cloud");
-          return Response.json(
-            { success: false, error: message },
-            { status: 500 },
-          );
-        }
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  // Literal path routes MUST come before parameterized `apps/:id/*` routes
+  // to prevent the `:id` param from capturing "shared", "fork", etc.
+
+  {
+    operationId: "apps_list",
+    endpoint: "apps",
+    method: "GET",
+    policyKey: "apps",
+    handler: handleListApps,
+    summary: "List apps",
+    description: "Return all locally installed apps.",
+    tags: ["apps"],
+    responseBody: z.object({
+      apps: z.array(z.unknown()).describe("Array of app summary objects"),
+    }),
+  },
+  {
+    operationId: "apps_open_bundle",
+    endpoint: "apps/open-bundle",
+    method: "POST",
+    policyKey: "apps/open-bundle",
+    handler: handleOpenBundle,
+    summary: "Open a .vbundle file",
+    description:
+      "Scan and validate a .vbundle file from disk and return its manifest.",
+    tags: ["apps"],
+    requestBody: z.object({
+      filePath: z.string().describe("Absolute path to the .vbundle file"),
+    }),
+  },
+  {
+    operationId: "apps_shared_list",
+    endpoint: "apps/shared",
+    method: "GET",
+    policyKey: "apps/shared-list",
+    handler: handleListSharedApps,
+    summary: "List shared apps",
+    description: "Return all apps available via cloud share links.",
+    tags: ["apps"],
+    responseBody: z.object({
+      apps: z.array(z.unknown()).describe("Array of shared app objects"),
+    }),
+  },
+  {
+    operationId: "apps_fork",
+    endpoint: "apps/fork",
+    method: "POST",
+    policyKey: "apps/fork",
+    handler: handleForkSharedApp,
+    summary: "Fork a shared app",
+    description: "Create a local copy of a shared app by its UUID.",
+    tags: ["apps"],
+    requestBody: z.object({
+      uuid: z.string().describe("UUID of the shared app to fork"),
+    }),
+  },
+  {
+    operationId: "apps_gallery_install",
+    endpoint: "apps/gallery/install",
+    method: "POST",
+    policyKey: "apps/gallery/install",
+    handler: handleInstallGalleryApp,
+    summary: "Install a gallery app",
+    description: "Install an app from the built-in gallery by its ID.",
+    tags: ["apps"],
+    requestBody: z.object({ galleryAppId: z.string() }),
+  },
+  {
+    operationId: "apps_gallery_list",
+    endpoint: "apps/gallery",
+    method: "GET",
+    policyKey: "apps/gallery",
+    handler: handleListGallery,
+    summary: "List gallery apps",
+    description: "Return the built-in app gallery catalog.",
+    tags: ["apps"],
+    responseBody: z.object({
+      gallery: z.array(z.unknown()).describe("Gallery app entries"),
+    }),
+  },
+  {
+    operationId: "apps_sign_bundle",
+    endpoint: "apps/sign-bundle",
+    method: "POST",
+    policyKey: "apps/sign-bundle",
+    handler: handleSignBundle,
+    summary: "Sign an app bundle",
+    description:
+      "Return a signing payload or complete the signing step when signature fields are provided.",
+    tags: ["apps"],
+    requestBody: z.object({
+      payload: z.string().describe("Canonical JSON payload to sign"),
+      signature: z.string().optional(),
+      keyId: z.string().optional(),
+      publicKey: z.string().optional(),
+    }),
+  },
+  {
+    operationId: "apps_signing_identity",
+    endpoint: "apps/signing-identity",
+    method: "GET",
+    policyKey: "apps/signing-identity",
+    handler: handleSigningIdentity,
+    summary: "Get signing identity",
+    description:
+      "Return signing identity info. Signing is managed client-side over HTTP.",
+    tags: ["apps"],
+  },
+
+  // Parameterized `apps/:id/*` routes — must follow all literal routes.
+
+  {
+    operationId: "apps_data_query",
+    endpoint: "apps/:id/data",
+    method: "GET",
+    policyKey: "apps/data",
+    handler: handleQueryAppData,
+    summary: "Query app data",
+    description: "Read records from an app's local data store.",
+    tags: ["apps"],
+    queryParams: [
+      {
+        name: "method",
+        type: "string",
       },
-    },
-  ];
-}
+    ],
+  },
+  {
+    operationId: "apps_data_mutate",
+    endpoint: "apps/:id/data",
+    method: "POST",
+    policyKey: "apps/data",
+    handler: handleMutateAppData,
+    summary: "Mutate app data",
+    description:
+      "Create, update, or delete records in an app's local data store.",
+    tags: ["apps"],
+    requestBody: z.object({
+      method: z.string().describe("'create', 'update', or 'delete'"),
+      recordId: z.string(),
+      data: z.object({}).passthrough(),
+    }),
+  },
+  {
+    operationId: "apps_open",
+    endpoint: "apps/:id/open",
+    method: "POST",
+    policyKey: "apps/open",
+    handler: handleOpenApp,
+    summary: "Open an app",
+    description:
+      "Compile (if needed) and return the app's HTML for rendering.",
+    tags: ["apps"],
+    responseBody: z.object({
+      appId: z.string(),
+      dirName: z.string(),
+      name: z.string(),
+      html: z.string(),
+    }),
+  },
+  {
+    operationId: "apps_delete",
+    endpoint: "apps/:id/delete",
+    method: "POST",
+    policyKey: "apps/delete",
+    handler: handleDeleteApp,
+    summary: "Delete an app",
+    description: "Permanently remove an app and its data.",
+    tags: ["apps"],
+  },
+  {
+    operationId: "apps_preview_get",
+    endpoint: "apps/:id/preview",
+    method: "GET",
+    policyKey: "apps/preview",
+    handler: handleGetPreview,
+    summary: "Get app preview",
+    description: "Return the preview image or HTML for an app.",
+    tags: ["apps"],
+  },
+  {
+    operationId: "apps_preview_update",
+    endpoint: "apps/:id/preview",
+    method: "PUT",
+    policyKey: "apps/preview",
+    handler: handleUpdatePreview,
+    summary: "Update app preview",
+    description: "Set a new preview image or HTML for an app.",
+    tags: ["apps"],
+    requestBody: z.object({
+      preview: z.string().describe("Base64-encoded image or HTML string"),
+    }),
+  },
+  {
+    operationId: "apps_history",
+    endpoint: "apps/:id/history",
+    method: "GET",
+    policyKey: "apps/history",
+    handler: handleGetHistory,
+    summary: "Get app version history",
+    description: "Return the git commit history of an app.",
+    tags: ["apps"],
+    queryParams: [{ name: "limit", type: "number" }],
+    responseBody: z.object({
+      appId: z.string(),
+      versions: z.array(z.unknown()),
+    }),
+  },
+  {
+    operationId: "apps_diff",
+    endpoint: "apps/:id/diff",
+    method: "GET",
+    policyKey: "apps/diff",
+    handler: handleGetDiff,
+    summary: "Get app diff",
+    description: "Return a git diff between two commits for an app.",
+    tags: ["apps"],
+    queryParams: [
+      { name: "fromCommit", type: "string", required: true },
+      { name: "toCommit", type: "string" },
+    ],
+  },
+  {
+    operationId: "apps_restore",
+    endpoint: "apps/:id/restore",
+    method: "POST",
+    policyKey: "apps/restore",
+    handler: handleRestore,
+    summary: "Restore app version",
+    description: "Restore an app to a previous git commit.",
+    tags: ["apps"],
+    requestBody: z.object({ commitHash: z.string() }),
+  },
+  {
+    operationId: "apps_bundle",
+    endpoint: "apps/:id/bundle",
+    method: "POST",
+    policyKey: "apps/bundle",
+    handler: handleBundle,
+    summary: "Bundle an app",
+    description: "Package an app into a distributable .vbundle archive.",
+    tags: ["apps"],
+    responseBody: z.object({
+      type: z.string(),
+      bundlePath: z.string(),
+      iconImageBase64: z.string(),
+      manifest: z.object({}).passthrough(),
+    }),
+  },
+  {
+    operationId: "apps_share_cloud",
+    endpoint: "apps/:id/share-cloud",
+    method: "POST",
+    policyKey: "apps/share-cloud",
+    handler: handleShareCloud,
+    summary: "Share app to cloud",
+    description: "Package and upload an app to the cloud share service.",
+    tags: ["apps"],
+    responseBody: z.object({
+      success: z.boolean(),
+      shareToken: z.string(),
+      shareUrl: z.string(),
+    }),
+  },
+];