@zuplo/editor 1.0.30627199824 → 1.0.30628139828

package/dist/app.d.ts

@@ -0,0 +1,67 @@
+import { type Context, Hono } from "hono";
+import { type LocalEditorLabels } from "./config.js";
+import type { CommonLogger } from "./interfaces.js";
+import type { ChangeNotifier, EditorPreferencesPort, FileSystemPort } from "./ports.js";
+/**
+ * The built SPA, however the platform happens to hold it.
+ *
+ * `serve` is handed the live Hono context rather than a path, because both
+ * implementations are thin wrappers over something that already expects one —
+ * `serveStatic` on Node, Cloudflare's assets binding in the Worker — and
+ * synthesising a context for them is what breaks.
+ */
+export interface AssetSource {
+    /**
+     * The `index.html` template, or `undefined` when there's no client build.
+     *
+     * Returned as a string because the config injection rewrites it per request.
+     */
+    readDocument(): Promise<string | undefined>;
+    /** The built asset the request is for, or `undefined` if there isn't one. */
+    serve(context: Context): Promise<Response | undefined>;
+}
+export interface EditorAppOptions {
+    /** The project the editor reads and writes. */
+    fs: FileSystemPort;
+    /** Where the user's external-editor choice is kept. */
+    preferences: EditorPreferencesPort;
+    /**
+     * The built SPA. Omit to run without one — Vite serves the client in
+     * development, and this app only answers `/api` in that case.
+     */
+    assets?: AssetSource;
+    /**
+     * Reports files changing underneath the editor, so the SPA can reload them.
+     * Omit to leave live-reload dormant.
+     */
+    changes?: ChangeNotifier;
+    logger: CommonLogger;
+    /** The gateway the test console relays requests to. */
+    deploymentUrl: string;
+    /**
+     * The project's location on the machine running the editor. Used only to build
+     * external-editor deep links; all file access goes through `fs`.
+     */
+    sourceDirectory: string;
+    /** Overrides for the account/environment names the portal displays. */
+    labels?: LocalEditorLabels;
+}
+export interface EditorApp {
+    /**
+     * The Hono app. Hand its `fetch` to whatever is listening — `@hono/node-server`
+     * on Node, the Worker's default export on Cloudflare.
+     */
+    app: Hono;
+    /** Releases SSE clients and stops listening for changes. */
+    dispose: () => Promise<void>;
+}
+/**
+ * Builds the editor's HTTP app from injected platform capabilities.
+ *
+ * This is the whole server minus the platform: no listener, no filesystem, no
+ * file watcher, no logger implementation. `LocalEditorServer` wraps it for Node
+ * and the preview Worker wraps it for Cloudflare, so both run these exact
+ * routes rather than approximations of each other.
+ */
+export declare function createEditorApp(options: EditorAppOptions): EditorApp;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE5C,6EAA6E;IAC7E,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,EAAE,EAAE,cAAc,CAAC;IAEnB,uDAAuD;IACvD,WAAW,EAAE,qBAAqB,CAAC;IAEnC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB,MAAM,EAAE,YAAY,CAAC;IAErB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB,uEAAuE;IACvE,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,GAAG,EAAE,IAAI,CAAC;IAEV,4DAA4D;IAC5D,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAoIpE"}

package/dist/app.js

@@ -0,0 +1,116 @@
+import { ApiError, HttpStatusCode } from "@zuplo/errors";
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { cors } from "hono/cors";
+import { getLocalEditorConfig } from "./config.js";
+import { editorConfig } from "./constants.js";
+import { createErrorHandler, createNotFoundHandler } from "./error-handler.js";
+import { createApiRoutes } from "./routes/api.js";
+const staticFileExtensions = [".css", ".js", ".json", ".svg", ".png", ".ico"];
+/**
+ * Builds the editor's HTTP app from injected platform capabilities.
+ *
+ * This is the whole server minus the platform: no listener, no filesystem, no
+ * file watcher, no logger implementation. `LocalEditorServer` wraps it for Node
+ * and the preview Worker wraps it for Cloudflare, so both run these exact
+ * routes rather than approximations of each other.
+ */
+export function createEditorApp(options) {
+    const { fs, preferences, assets, changes, logger, deploymentUrl, sourceDirectory, labels, } = options;
+    const app = new Hono();
+    const sseClients = new Set();
+    app.onError(createErrorHandler(logger));
+    app.notFound(createNotFoundHandler());
+    // Middleware only wraps routes registered after it, so this has to come
+    // before the routes below.
+    app.use(bodyLimit({
+        maxSize: editorConfig.server.bodyLimit,
+        onError: () => {
+            throw new ApiError({
+                type: "https://zup.fail/http-status/413",
+                title: "Payload Too Large",
+                status: HttpStatusCode.PAYLOAD_TOO_LARGE,
+                detail: `Request body exceeds the maximum size of ${editorConfig.server.bodyLimit} bytes`,
+            });
+        },
+    }));
+    app.use(cors({
+        origin: (origin) => origin ?? "*",
+        allowMethods: [
+            "GET",
+            "POST",
+            "PATCH",
+            "PUT",
+            "DELETE",
+            "OPTIONS",
+            "HEAD",
+        ],
+        allowHeaders: ["*"],
+        exposeHeaders: ["*"],
+    }));
+    app.route("/api", createApiRoutes({
+        fs,
+        editorPreferences: preferences,
+        sourceDirectory,
+        logger,
+        sseClients,
+        deploymentUrl,
+    }));
+    if (assets) {
+        app.on(["GET", "HEAD"], "*", async (c) => {
+            const isDocumentRequest = c.req.header("accept")?.includes("text/html") &&
+                !staticFileExtensions.some((ext) => c.req.path.endsWith(ext));
+            if (!isDocumentRequest) {
+                return ((await assets.serve(c)) ??
+                    // The asset source hands misses back rather than 404ing itself, so
+                    // they get the same problem+json every other miss does.
+                    c.notFound());
+            }
+            // Every navigation gets index.html — the SPA owns routing.
+            const template = await assets.readDocument();
+            if (!template) {
+                // No client build yet, which is normal in development: Vite is in front
+                // and this handler is never reached there.
+                return c.notFound();
+            }
+            const localEditorConfig = await getLocalEditorConfig({
+                deploymentUrl,
+                fs,
+                logger,
+                labels,
+            });
+            // Inject localEditorConfig into the HTML
+            const html = template.replace(`"{{localEditorConfig}}"`, // Note the quotes are correct
+            // A replacer function, so `$&` and friends in the JSON aren't treated
+            // as substitution patterns.
+            () => JSON.stringify(localEditorConfig));
+            return c.html(html);
+        });
+    }
+    const stopWatching = changes?.onChange((filePath) => {
+        // Broadcast to all SSE clients
+        const data = JSON.stringify({ type: "change", filePath });
+        for (const client of sseClients) {
+            client.send("change", data).catch((err) => {
+                logger.warn({ err }, "Error sending SSE change event");
+            });
+        }
+        logger.info(`File changed: ${filePath}`);
+    });
+    const dispose = async () => {
+        stopWatching?.();
+        for (const client of sseClients) {
+            try {
+                if (!client.closed) {
+                    await client.close();
+                }
+            }
+            catch (err) {
+                logger.warn({ err }, "Error closing SSE client");
+            }
+        }
+        sseClients.clear();
+    };
+    return { app, dispose };
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { CommonLogger } from "./interfaces.js";
 import { type ApeContext } from "./interfaces.portal.js";
+import type { FileSystemPort } from "./ports.js";
 /**
  * Local-specific configuration that is provided to the React app
  *
@@ -10,9 +11,22 @@ export interface LocalEditorConfig {
     defaultPath: string;
     apeContext: ApeContext;
 }
-export declare function getLocalEditorConfig({ deploymentUrl, sourceDirectory, logger }: {
+/**
+ * Human-readable names shown in the portal's account and environment chrome.
+ *
+ * The preview Worker overrides these so a hosted preview identifies itself as
+ * one — with its branch and commit — instead of claiming to be somebody's local
+ * machine. That reuses UI the portal already renders, so nothing preview-only
+ * has to exist in the frontend.
+ */
+export interface LocalEditorLabels {
+    account?: string;
+    environment?: string;
+}
+export declare function getLocalEditorConfig({ deploymentUrl, fs, logger, labels }: {
     deploymentUrl: string;
-    sourceDirectory: string;
+    fs: FileSystemPort;
     logger: CommonLogger;
+    labels?: LocalEditorLabels;
 }): Promise<LocalEditorConfig>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAEL,KAAK,UAAU,EAIhB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAIhC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB;AAaD,wBAAsB,oBAAoB,CAAC,EACzC,aAAa,EACb,eAAe,EACf,MAAM,EACP,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6G7B"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAEL,KAAK,UAAU,EAIhB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAIhC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB;AAaD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,oBAAoB,CAAC,EACzC,aAAa,EACb,EAAE,EACF,MAAM,EACN,MAAM,EACP,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,cAAc,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4G7B"}

package/dist/config.js

@@ -1,4 +1,3 @@
-import { readFile } from "node:fs/promises";
 import { EnvironmentType, } from "./interfaces.portal.js";
 function npmNameToUrlSafe(name) {
     // Scoped packages: @scope/pkg -> scope-pkg
@@ -8,10 +7,11 @@ function npmNameToUrlSafe(name) {
     // Other names: just URI encode to be safe
     return encodeURIComponent(name.toLowerCase());
 }
-export async function getLocalEditorConfig({ deploymentUrl, sourceDirectory, logger, }) {
+export async function getLocalEditorConfig({ deploymentUrl, fs, logger, labels, }) {
     let pkgJson;
     try {
-        pkgJson = (await readFile(`${sourceDirectory}/package.json`, "utf-8").then(JSON.parse));
+        const { content } = await fs.readFileWithStat("package.json");
+        pkgJson = JSON.parse(content);
     }
     catch (err) {
         logger.warn({ err }, "Failed to load package.json");
@@ -20,7 +20,7 @@ export async function getLocalEditorConfig({ deploymentUrl, sourceDirectory, log
     const account = {
         id: "dev",
         name: "dev",
-        label: "Local Development",
+        label: labels?.account ?? "Local Development",
         createdOn: new Date().toISOString(),
         isSharingEnabled: false,
         isMfaEnforced: false,
@@ -70,7 +70,7 @@ export async function getLocalEditorConfig({ deploymentUrl, sourceDirectory, log
     const environmentName = `local-${projectName}`;
     const environment = {
         name: environmentName,
-        label: "local",
+        label: labels?.environment ?? "local",
         urlParameter: environmentName,
         createdOn: Date.now(),
         accountName: account.name,

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/fixtures/preview-project.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The sample Zuplo project the editor preview deployment starts from, as
+ * project-relative path → file content.
+ */
+export declare const previewProject: Record<string, string>;
+//# sourceMappingURL=preview-project.d.ts.map

package/dist/fixtures/preview-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-project.d.ts","sourceRoot":"","sources":["../../src/fixtures/preview-project.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuBjD,CAAC"}

package/dist/fixtures/preview-project.js

@@ -0,0 +1,21 @@
+// Generated by scripts/build-fixture.ts — do not edit.
+// Regenerate with `pnpm --filter @zuplo/editor build:fixture` after changing
+// anything under fixtures/preview-project.
+/**
+ * The sample Zuplo project the editor preview deployment starts from, as
+ * project-relative path → file content.
+ */
+export const previewProject = {
+    "config/policies.json": '{\n  "policies": [\n    {\n      "name": "api-key-auth",\n      "policyType": "api-key-inbound",\n      "handler": {\n        "export": "ApiKeyInboundPolicy",\n        "module": "$import(@zuplo/runtime)",\n        "options": {\n          "allowUnauthenticatedRequests": false\n        }\n      }\n    },\n    {\n      "name": "rate-limit-products",\n      "policyType": "rate-limit-inbound",\n      "handler": {\n        "export": "RateLimitInboundPolicy",\n        "module": "$import(@zuplo/runtime)",\n        "options": {\n          "rateLimitBy": "ip",\n          "requestsAllowed": 100,\n          "timeWindowMinutes": 1\n        }\n      }\n    },\n    {\n      "name": "validate-product",\n      "policyType": "request-validation-inbound",\n      "handler": {\n        "export": "RequestValidationInboundPolicy",\n        "module": "$import(@zuplo/runtime)",\n        "options": {\n          "validateBody": true,\n          "includeRequestInLogs": true\n        }\n      }\n    }\n  ]\n}\n',
+    "config/routes.oas.json": '{\n  "openapi": "3.1.0",\n  "info": {\n    "title": "Preview Gateway",\n    "version": "1.0.0",\n    "description": "A sample API used by the editor preview deployment."\n  },\n  "paths": {\n    "/products": {\n      "get": {\n        "summary": "List products",\n        "operationId": "list-products",\n        "x-zuplo-route": {\n          "corsPolicy": "anything-goes",\n          "handler": {\n            "export": "urlForwardHandler",\n            "module": "$import(@zuplo/runtime)",\n            "options": {\n              "baseUrl": "https://echo.zuplo.io/products"\n            }\n          },\n          "policies": {\n            "inbound": ["rate-limit-products", "api-key-auth"]\n          }\n        },\n        "responses": {\n          "200": {\n            "description": "A page of products",\n            "content": {\n              "application/json": {\n                "schema": { "$ref": "../schemas/product-list.json" }\n              }\n            }\n          }\n        }\n      },\n      "post": {\n        "summary": "Create a product",\n        "operationId": "create-product",\n        "x-zuplo-route": {\n          "corsPolicy": "anything-goes",\n          "handler": {\n            "export": "default",\n            "module": "$import(./modules/create-product)"\n          },\n          "policies": {\n            "inbound": ["validate-product", "api-key-auth"]\n          }\n        },\n        "requestBody": {\n          "required": true,\n          "content": {\n            "application/json": {\n              "schema": { "$ref": "../schemas/product.json" }\n            }\n          }\n        },\n        "responses": {\n          "201": { "description": "The created product" }\n        }\n      }\n    },\n    "/products/:productId": {\n      "get": {\n        "summary": "Get a product",\n        "operationId": "get-product",\n        "x-zuplo-route": {\n          "corsPolicy": "anything-goes",\n          "handler": {\n            "export": "getProduct",\n            "module": "$import(./modules/get-product)"\n          },\n          "policies": {\n            "inbound": ["api-key-auth"]\n          }\n        },\n        "responses": {\n          "200": { "description": "The product" },\n          "404": { "description": "No such product" }\n        }\n      }\n    },\n    "/health": {\n      "get": {\n        "summary": "Health check",\n        "operationId": "health",\n        "x-zuplo-route": {\n          "corsPolicy": "anything-goes",\n          "handler": {\n            "export": "health",\n            "module": "$import(./modules/health)"\n          }\n        },\n        "responses": {\n          "200": { "description": "The gateway is up" }\n        }\n      }\n    }\n  }\n}\n',
+    "docs/introduction.md": '---\ntitle: Introduction\n---\n\n# Preview Gateway\n\nThis is a sample Zuplo project. It exists so the editor\'s per-PR preview\ndeployment has a realistic project to render — routes with policies attached,\nJSON schemas, handler modules, tests, and these docs.\n\n## Authentication\n\nEvery route except `/health` requires an API key:\n\n```bash\ncurl https://example.com/products \\\n  -H "Authorization: Bearer $API_KEY"\n```\n\n## Rate limits\n\n`GET /products` is limited to 100 requests per minute per IP.\n',
+    "modules/create-product.ts": 'import { ZuploContext, ZuploRequest } from "@zuplo/runtime";\n\ninterface NewProduct {\n  name: string;\n  price: number;\n}\n\nexport default async function (request: ZuploRequest, context: ZuploContext) {\n  const body = (await request.json()) as NewProduct;\n\n  context.log.info(`Creating product ${body.name}`);\n\n  return new Response(\n    JSON.stringify({ id: crypto.randomUUID(), ...body }),\n    {\n      status: 201,\n      headers: { "content-type": "application/json" },\n    },\n  );\n}\n',
+    "modules/get-product.ts": 'import { ZuploContext, ZuploRequest } from "@zuplo/runtime";\n\nconst products: Record<string, { id: string; name: string; price: number }> = {\n  "1": { id: "1", name: "Espresso Machine", price: 449 },\n  "2": { id: "2", name: "Burr Grinder", price: 179 },\n};\n\nexport async function getProduct(request: ZuploRequest, context: ZuploContext) {\n  const { productId } = request.params;\n  const product = products[productId];\n\n  if (!product) {\n    context.log.warn(`No product with id ${productId}`);\n    return new Response("Not found", { status: 404 });\n  }\n\n  return product;\n}\n',
+    "modules/health.ts": 'import { ZuploContext, ZuploRequest } from "@zuplo/runtime";\n\nexport function health(request: ZuploRequest, context: ZuploContext) {\n  return { status: "ok" };\n}\n',
+    "package.json": '{\n  "name": "preview-gateway",\n  "version": "1.0.0",\n  "private": true,\n  "description": "Sample Zuplo project served by the editor preview deployment"\n}\n',
+    "schemas/product-list.json": '{\n  "$schema": "http://json-schema.org/draft-07/schema#",\n  "title": "ProductList",\n  "type": "object",\n  "required": ["data"],\n  "properties": {\n    "data": {\n      "type": "array",\n      "items": { "$ref": "./product.json" }\n    },\n    "nextCursor": {\n      "type": ["string", "null"]\n    }\n  }\n}\n',
+    "schemas/product.json": '{\n  "$schema": "http://json-schema.org/draft-07/schema#",\n  "title": "Product",\n  "type": "object",\n  "required": ["name", "price"],\n  "additionalProperties": false,\n  "properties": {\n    "id": {\n      "type": "string",\n      "description": "Server-assigned identifier."\n    },\n    "name": {\n      "type": "string",\n      "minLength": 1,\n      "maxLength": 200\n    },\n    "price": {\n      "type": "number",\n      "minimum": 0\n    }\n  }\n}\n',
+    "tests/products.test.ts": 'import { describe, expect, it } from "@zuplo/test";\n\ndescribe("products", () => {\n  it("lists products", async () => {\n    const response = await fetch(`${process.env.ZUPLO_URL}/products`);\n    expect(response.status).toBe(200);\n  });\n\n  it("rejects a product with no name", async () => {\n    const response = await fetch(`${process.env.ZUPLO_URL}/products`, {\n      method: "POST",\n      headers: { "content-type": "application/json" },\n      body: JSON.stringify({ price: 10 }),\n    });\n    expect(response.status).toBe(400);\n  });\n});\n',
+    "zuplo.jsonc": '{\n  // Sample project for the editor preview deployment. `version` pins the\n  // runtime the gateway would build against.\n  "version": 1,\n  "runtime": {\n    "compatibilityDate": "2026-05-19"\n  }\n}\n',
+};
+//# sourceMappingURL=preview-project.js.map

package/dist/fixtures/preview-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-project.js","sourceRoot":"","sources":["../../src/fixtures/preview-project.ts"],"names":[],"mappings":"AAAA,yDAAuD;AACvD,6EAA6E;AAC7E,2CAA2C;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,sBAAsB,EACpB,u+BAAu+B;IACz+B,wBAAwB,EACtB,gsFAAgsF;IAClsF,sBAAsB,EACpB,qgBAAmgB;IACrgB,2BAA2B,EACzB,yfAAyf;IAC3f,wBAAwB,EACtB,klBAAklB;IACplB,mBAAmB,EACjB,yKAAyK;IAC3K,cAAc,EACZ,kKAAkK;IACpK,2BAA2B,EACzB,4TAA4T;IAC9T,sBAAsB,EACpB,8cAA8c;IAChd,wBAAwB,EACtB,6iBAA6iB;IAC/iB,aAAa,EACX,+MAA+M;CAClN,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
+export { type AssetSource, createEditorApp, type EditorApp, type EditorAppOptions, } from "./app.js";
+export { getLocalEditorConfig, type LocalEditorConfig, type LocalEditorLabels, } from "./config.js";
+export { type ChangeNotifier, type DirEntry, type EditorPreferencesPort, type FileSystemPort, type FileWithStat, PathNotFoundError, type PathStat, type PathType, UnsafePathError, } from "./ports.js";
 export { type LocalEditorOptions, LocalEditorServer } from "./server.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,iBAAiB,EACjB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,5 @@
+export { createEditorApp, } from "./app.js";
+export { getLocalEditorConfig, } from "./config.js";
+export { PathNotFoundError, UnsafePathError, } from "./ports.js";
 export { LocalEditorServer } from "./server.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,GAGhB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,oBAAoB,GAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAML,iBAAiB,EAGjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAA2B,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/ports.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The platform capabilities the editor's routes need, stated in the routes' own
+ * terms rather than as a subset of `node:fs`.
+ *
+ * Everything here is injected, so the same Hono app runs against a developer's
+ * real project directory (the Zuplo CLI) and against an in-memory project (the
+ * per-PR preview Worker). Keeping the seam this narrow is what stops the two
+ * from drifting: a route can't reach for `node:fs` without adding a method
+ * here, and the preview build fails when something does.
+ */
+/**
+ * A path that escaped the project root, e.g. `?path=../../../etc/passwd`.
+ *
+ * Rejecting traversal is the port's job rather than each route's, because a
+ * route that forgets is a directory-traversal hole and there is no other
+ * chokepoint every path passes through.
+ */
+export declare class UnsafePathError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * A path that doesn't exist.
+ *
+ * Routes branch on this instead of on `ENOENT`, so a miss reports identically
+ * however the filesystem is implemented — the case an errno-shaped port gets
+ * subtly wrong.
+ */
+export declare class PathNotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export type PathType = "file" | "directory";
+export interface DirEntry {
+    /** The entry's own name, not a path. */
+    name: string;
+    type: PathType;
+}
+export interface PathStat {
+    type: PathType;
+    mtime: Date;
+}
+export interface FileWithStat {
+    content: string;
+    /** The mtime of the content returned alongside it — see `readFileWithStat`. */
+    mtime: Date;
+}
+/**
+ * A project directory the editor can read and write.
+ *
+ * Every path is relative to the project root and slash-separated
+ * (`config/routes.oas.json`), with or without a leading slash. Implementations
+ * reject paths that climb out of the root with `UnsafePathError`.
+ */
+export interface FileSystemPort {
+    /**
+     * Reads a file and the mtime describing *that* content, together.
+     *
+     * The pair has to be consistent: the portal saves the returned mtime as
+     * `Last-Modified` and sends it back as `If-Unmodified-Since` to detect
+     * clobbering, so a stat taken separately from the read can describe a
+     * different version of the file and produce phantom conflicts — or miss real
+     * ones. How that's achieved is the adapter's problem (Node holds a single
+     * file handle open across both).
+     *
+     * @throws PathNotFoundError when the file doesn't exist.
+     */
+    readFileWithStat(path: string): Promise<FileWithStat>;
+    /**
+     * Lists a directory's immediate children. Order is not significant.
+     *
+     * @throws PathNotFoundError when the directory doesn't exist.
+     */
+    listDir(path: string): Promise<DirEntry[]>;
+    /** Returns `undefined` when nothing exists at `path`. */
+    statPath(path: string): Promise<PathStat | undefined>;
+    /**
+     * Writes a file, creating any missing parent directories, and returns the
+     * stat it now has — the caller hands that mtime straight back to the client.
+     */
+    writeFile(path: string, content: string | Uint8Array): Promise<PathStat>;
+    /** @throws PathNotFoundError when `from` doesn't exist. */
+    rename(from: string, to: string): Promise<void>;
+    /** @throws PathNotFoundError when `path` doesn't exist. */
+    remove(path: string): Promise<void>;
+    /** Creates a directory and any missing parents. Succeeds if it exists. */
+    mkdirp(path: string): Promise<void>;
+}
+/**
+ * Which external editor the user picked for "open in editor".
+ *
+ * Separate from `FileSystemPort` because this lives outside the project — an
+ * XDG config file under the user's home directory on Node, and nowhere at all
+ * in a Worker, which has no home directory to write to.
+ */
+export interface EditorPreferencesPort {
+    /** The saved editor id, or `null` if the user hasn't chosen one. */
+    get(): Promise<string | null>;
+    set(editor: string): Promise<void>;
+}
+/**
+ * Tells the editor a file changed underneath it, so the SPA can reload it.
+ *
+ * On Node this is chokidar watching the project directory. In the preview it's
+ * the in-memory filesystem reporting its own writes, which is what keeps the
+ * SPA's live-reload path exercised there rather than dormant.
+ */
+export interface ChangeNotifier {
+    /**
+     * Registers `listener`, called with a project-relative path on each change.
+     * Returns a function that unsubscribes.
+     */
+    onChange(listener: (path: string) => void): () => void;
+}
+/**
+ * Splits a project-relative path into its segments, rejecting anything that
+ * climbs out of the project or isn't relative to begin with.
+ *
+ * Both adapters route every path through this, so traversal is refused once, at
+ * the boundary, instead of relying on each route to remember.
+ */
+export declare function toSafeSegments(path: string): string[];
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAIvB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAIvB;CACF;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE5C,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,IAAI,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAA+E;IAC/E,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEtD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE3C,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAEtD;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEzE,2DAA2D;IAC3D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD,2DAA2D;IAC3D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,GAAG,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACxD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBrD"}

package/dist/ports.js

@@ -0,0 +1,71 @@
+/**
+ * The platform capabilities the editor's routes need, stated in the routes' own
+ * terms rather than as a subset of `node:fs`.
+ *
+ * Everything here is injected, so the same Hono app runs against a developer's
+ * real project directory (the Zuplo CLI) and against an in-memory project (the
+ * per-PR preview Worker). Keeping the seam this narrow is what stops the two
+ * from drifting: a route can't reach for `node:fs` without adding a method
+ * here, and the preview build fails when something does.
+ */
+/**
+ * A path that escaped the project root, e.g. `?path=../../../etc/passwd`.
+ *
+ * Rejecting traversal is the port's job rather than each route's, because a
+ * route that forgets is a directory-traversal hole and there is no other
+ * chokepoint every path passes through.
+ */
+export class UnsafePathError extends Error {
+    path;
+    constructor(path) {
+        super(`Path escapes the project directory: ${path}`);
+        this.name = "UnsafePathError";
+        this.path = path;
+    }
+}
+/**
+ * A path that doesn't exist.
+ *
+ * Routes branch on this instead of on `ENOENT`, so a miss reports identically
+ * however the filesystem is implemented — the case an errno-shaped port gets
+ * subtly wrong.
+ */
+export class PathNotFoundError extends Error {
+    path;
+    constructor(path) {
+        super(`Path not found: ${path}`);
+        this.name = "PathNotFoundError";
+        this.path = path;
+    }
+}
+/**
+ * Splits a project-relative path into its segments, rejecting anything that
+ * climbs out of the project or isn't relative to begin with.
+ *
+ * Both adapters route every path through this, so traversal is refused once, at
+ * the boundary, instead of relying on each route to remember.
+ */
+export function toSafeSegments(path) {
+    // A Windows drive letter or a UNC path is absolute but survives POSIX
+    // normalization, so it has to be caught by shape rather than by segment.
+    if (/^[a-zA-Z]:/.test(path) || path.startsWith("\\\\")) {
+        throw new UnsafePathError(path);
+    }
+    const segments = [];
+    // Backslashes are separators on Windows; treating them as ordinary characters
+    // would let `..\..` through as a single innocuous-looking segment.
+    for (const segment of path.split(/[/\\]+/)) {
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            // Refuse rather than resolve. `config/../modules` is legitimate but
+            // nothing the portal sends, and allowing it means the guard depends on
+            // segment order — every prefix would have to stay inside the root too.
+            throw new UnsafePathError(path);
+        }
+        segments.push(segment);
+    }
+    return segments;
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE;QACxB,KAAK,CAAC,uCAAuC,IAAI,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAAA,CAClB;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE;QACxB,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAAA,CAClB;CACF;AAiGD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAY;IACrD,sEAAsE;IACtE,yEAAyE;IACzE,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,8EAA8E;IAC9E,mEAAmE;IACnE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,oEAAoE;YACpE,uEAAuE;YACvE,yEAAuE;YACvE,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,QAAQ,CAAC;AAAA,CACjB"}

package/dist/routes/api.d.ts

@@ -1,7 +1,12 @@
 import { Hono } from "hono";
 import type { CommonLogger, SseClient } from "../interfaces.js";
+import type { EditorPreferencesPort, FileSystemPort } from "../ports.js";
 interface ApiRoutesOptions {
+    /** Only used to build external-editor deep links — file access goes via `fs`. */
     sourceDirectory: string;
+    fs: FileSystemPort;
+    /** Distinct from the portal's own user preferences stubbed further down. */
+    editorPreferences: EditorPreferencesPort;
     logger: CommonLogger;
     sseClients: Set<SseClient>;
     deploymentUrl: string;

package/dist/routes/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/routes/api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQhE,UAAU,gBAAgB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAkI/D"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/routes/api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQzE,UAAU,gBAAgB;IACxB,mFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;IACxB,EAAE,EAAE,cAAc,CAAC;IACnB,4EAA4E;IAC5E,iBAAiB,EAAE,qBAAqB,CAAC;IACzC,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CA+I/D"}

package/dist/routes/api.js

@@ -12,12 +12,15 @@ const PreferencesBody = Type.Object({
     data: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 });
 export function createApiRoutes(options) {
-    const { sourceDirectory, logger, sseClients, deploymentUrl } = options;
+    const { sourceDirectory, fs, editorPreferences, logger, sseClients, deploymentUrl, } = options;
     const app = new Hono();
     // Filesystem routes
-    app.route("/v1/deployments/:deploymentName/fs", createFsRoutes({ sourceDirectory, logger }));
+    app.route("/v1/deployments/:deploymentName/fs", createFsRoutes({ fs, logger }));
     // Editor routes (for opening files in external editor)
-    app.route("/v1/editor", createEditorRoutes({ sourceDirectory }));
+    app.route("/v1/editor", createEditorRoutes({
+        sourceDirectory,
+        preferences: editorPreferences,
+    }));
     // Test routes (for proxying test requests to local Zuplo gateway). Mounted
     // twice because Fastify answered on both spellings and Hono doesn't: the
     // portal posts to /v1/test, but the real test-proxy accepts either.
@@ -70,11 +73,11 @@ export function createApiRoutes(options) {
     // state from GET /users/me/preferences (and writes via PUT). Local mode has
     // no real user store — keep an in-memory copy for the process lifetime so
     // the editor can load and the expand/collapse toggle still works in-session.
-    let preferences = {};
-    app.get("/v1/users/me/preferences", (c) => c.json({ data: preferences }));
+    let userPreferences = {};
+    app.get("/v1/users/me/preferences", (c) => c.json({ data: userPreferences }));
     app.put("/v1/users/me/preferences", validate("json", PreferencesBody), (c) => {
-        preferences = c.req.valid("json").data ?? {};
-        return c.json({ data: preferences });
+        userPreferences = c.req.valid("json").data ?? {};
+        return c.json({ data: userPreferences });
     });
     // Get deployment info (includes URL for local gateway)
     app.get("/v1/deployments/:deploymentName", (c) => c.json({