@xtrable-ltd/nanoesis 0.1.21 → 0.1.22

package/dist/adapter-azure-blob.d.ts

@@ -1,5 +1,5 @@
 import { ContainerClient } from '@azure/storage-blob';
-import { BlobStore, ArtifactSink } from '@nanoesis/engine';
+import { BlobStore, ArtifactSink, Storage } from '@nanoesis/engine';
 export { contentTypeFor } from '@nanoesis/engine';
 
 /**
@@ -34,7 +34,7 @@ declare class InMemoryBlobContainer implements BlobContainer {
     constructor(seed?: Readonly<Record<string, Uint8Array | string>>);
     list(prefix: string): Promise<readonly string[]>;
     read(name: string): Promise<Uint8Array | null>;
-    write(name: string, data: Uint8Array): Promise<void>;
+    write(name: string, data: Uint8Array, contentType?: string): Promise<void>;
     remove(name: string): Promise<void>;
     /** Test helper: the current blob names. */
     get names(): readonly string[];
@@ -90,6 +90,15 @@ declare class BlobArtifactSink implements ArtifactSink {
     write(path: string, contents: string | Uint8Array): Promise<void>;
 }
 
+/**
+ * A ready-made {@link Storage} over an Azure Blob container: get/put/delete (via
+ * {@link BlobContainerStore}) plus `wipe` (delete every blob). Pass it to `createEditor`
+ * as `editorFiles` (the working container) and `website` (the published `$web` container).
+ * For the working container, also pass `enumerate: () => container.list('')` so the editor
+ * can reconcile its content index.
+ */
+declare function azureStorage(container: BlobContainer): Storage;
+
 /**
  * Pure path/name helper for the blob adapters. Blob storage is a *flat* namespace, a blob
  * is just a name like "content/blog/post.json", so the only mapping the SDK glue needs is
@@ -100,4 +109,4 @@ declare class BlobArtifactSink implements ArtifactSink {
 /** Normalise a site path to a blob name: forward slashes, no leading/trailing slash. */
 declare function normalizeBlobName(path: string): string;
 
-export { AzureBlobContainer, BlobArtifactSink, type BlobContainer, BlobContainerStore, InMemoryBlobContainer, normalizeBlobName };
+export { AzureBlobContainer, BlobArtifactSink, type BlobContainer, BlobContainerStore, InMemoryBlobContainer, azureStorage, normalizeBlobName };

package/dist/adapter-azure-blob.js

@@ -20,7 +20,8 @@ var InMemoryBlobContainer = class {
   async read(name) {
     return this.blobs.get(name) ?? null;
   }
-  async write(name, data) {
+  async write(name, data, contentType) {
+    void contentType;
     this.blobs.set(name, data);
   }
   async remove(name) {
@@ -117,11 +118,25 @@ var BlobArtifactSink = class {
     await this.container.write(name, data, contentTypeFor(name));
   }
 };
+
+// ../../adapters/azure-blob/src/azure-storage.ts
+function azureStorage(container) {
+  const store = new BlobContainerStore(container);
+  return {
+    get: (key) => store.get(key),
+    put: (key, bytes) => store.put(key, bytes),
+    delete: (key) => store.delete(key),
+    wipe: async () => {
+      for (const name of await container.list("")) await container.remove(name);
+    }
+  };
+}
 export {
   AzureBlobContainer,
   BlobArtifactSink,
   BlobContainerStore,
   InMemoryBlobContainer,
+  azureStorage,
   contentTypeFor,
   normalizeBlobName
 };

package/dist/adapter-fs.d.ts

@@ -1,4 +1,4 @@
-import { BlobStore, ArtifactSink } from '@nanoesis/engine';
+import { BlobStore, ArtifactSink, Storage } from '@nanoesis/engine';
 
 /**
  * Filesystem implementation of the engine's {@link BlobStore} port (DESIGN §11c): get /
@@ -35,4 +35,13 @@ declare class FsArtifactSink implements ArtifactSink {
     wipe(): Promise<void>;
 }
 
-export { FsArtifactSink, FsBlobStore };
+/**
+ * A ready-made {@link Storage} over a local directory: get/put/delete (via
+ * {@link FsBlobStore}) plus `wipe` (remove the directory). Pass it straight to
+ * `createEditor` as `editorFiles` and/or `website` for a zero-implementation local host
+ * (DESIGN §11c): `createEditor({ editorFiles: folderStorage('./site'), website:
+ * folderStorage('./public'), login: devNoAuth() })`.
+ */
+declare function folderStorage(root: string): Storage;
+
+export { FsArtifactSink, FsBlobStore, folderStorage };

package/dist/adapter-fs.js

@@ -48,7 +48,20 @@ var FsArtifactSink = class {
     await rm2(this.root, { recursive: true, force: true });
   }
 };
+
+// ../../adapters/fs/src/folder-storage.ts
+import { rm as rm3 } from "fs/promises";
+function folderStorage(root) {
+  const blobs = new FsBlobStore(root);
+  return {
+    get: (key) => blobs.get(key),
+    put: (key, bytes) => blobs.put(key, bytes),
+    delete: (key) => blobs.delete(key),
+    wipe: () => rm3(root, { recursive: true, force: true })
+  };
+}
 export {
   FsArtifactSink,
-  FsBlobStore
+  FsBlobStore,
+  folderStorage
 };

package/dist/{chunk-26VCV3IE.js → chunk-SHGYQTZ7.js}

@@ -1,4 +1,5 @@
 import {
+  IndexedStore,
   analyzeTemplate,
   applyMigration,
   baseTemplateName,
@@ -12,6 +13,7 @@ import {
   loadComponents,
   loadTemplate,
   pendingMigrations,
+  publishSite,
   renderReferenceMarkdown,
   validateSite,
   workingStoreRoundTripDiagnostic
@@ -633,202 +635,6 @@ function authorDirectory(users) {
   };
 }
 
-// ../editor-api/src/mcp.ts
-function str(args, key) {
-  const value = args[key];
-  return typeof value === "string" ? value : "";
-}
-function request(method, path, query, bodyText, token) {
-  const body = bodyText === void 0 ? new Uint8Array() : new TextEncoder().encode(bodyText);
-  return {
-    method,
-    path,
-    query: new URLSearchParams(query),
-    getHeader: (name) => name.toLowerCase() === "authorization" && token !== void 0 ? `Bearer ${token}` : void 0,
-    body: async () => body
-  };
-}
-var pathArg = {
-  type: "string",
-  description: 'Site-relative path with forward slashes, e.g. "content/blog/post.json".'
-};
-var TOOL_SPECS = [
-  {
-    name: "list_dir",
-    description: "List the immediate children (files and folders) of a site directory. Use '' or omit for the site root; the top-level folders are content/ (pages), templates/, components/, and public/.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: { type: "string", description: "Directory path, '' for the site root." }
-      },
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("GET", "/api/list", { dir: str(args, "path") }, void 0, token)
-  },
-  {
-    name: "read_file",
-    description: "Read a file's text contents (content JSON, a template/component's HTML, CSS, etc.). Reports an error if the file does not exist.",
-    inputSchema: {
-      type: "object",
-      properties: { path: pathArg },
-      required: ["path"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("GET", "/api/read", { path: str(args, "path") }, void 0, token)
-  },
-  {
-    name: "describe_template",
-    description: "List the fields a template defines (name, type, label, whether required, length limits), so you know what a page using it needs. Pass the template name without its path or extension, e.g. 'article' for templates/article.html.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        name: {
-          type: "string",
-          description: 'Template name without path or extension, e.g. "article".'
-        }
-      },
-      required: ["name"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("GET", "/api/template-fields", { name: str(args, "name") }, void 0, token)
-  },
-  {
-    name: "write_file",
-    description: "Create or overwrite a text file. content/ requires the author role; templates/, components/, and public/ require the developer role. Read the nanoesis://reference resource first for the authoring syntax. For template/component paths the response includes `schemaDelta` (added/removed/typeChanged fields) \u2014 if `typeChanged` contains `destructive: true` or `removed` is non-empty, an auto-stamp has been written and authored content may need migration, so surface to the user before further edits. For content/*.json writes the response may include `parseDiagnostics.unknownTopLevelKeys` \u2014 top-level keys the parser dropped because they are not system keys; content values belong under `fields` (system keys are case-sensitive: `isPublished`, not `IsPublished`). See the reference's 'Authoring guardrails for LLMs' section for the common pitfalls (notably: `data-*` annotations bind to the element, not the token inside it \u2014 moving a token out of its annotated container silently strips them).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: pathArg,
-        contents: { type: "string", description: "The full new text contents of the file." }
-      },
-      required: ["path", "contents"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("POST", "/api/write", { path: str(args, "path") }, str(args, "contents"), token)
-  },
-  {
-    name: "delete_path",
-    description: "Delete a file or a whole folder subtree. Same role rules as write_file. Deleting a path that does not exist is a no-op.",
-    inputSchema: {
-      type: "object",
-      properties: { path: pathArg },
-      required: ["path"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("POST", "/api/delete", { path: str(args, "path") }, void 0, token)
-  },
-  {
-    name: "rename_path",
-    description: "Move or rename a file or folder subtree. Refuses to overwrite an existing destination. Requires write rights at both the source and the destination. Renaming a template also requires updating every content item bound to the old name (the validation gate will catch unbound items on publish, but `list_pending_migrations` is the cheaper check).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        from: { type: "string", description: "The current path." },
-        to: { type: "string", description: "The new path." }
-      },
-      required: ["from", "to"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request(
-      "POST",
-      "/api/rename",
-      { from: str(args, "from"), to: str(args, "to") },
-      void 0,
-      token
-    )
-  },
-  {
-    name: "validate",
-    description: "Run the validation gate over the whole site and return its diagnostics, without publishing. Use it to check your work: errors would block a publish, warnings (e.g. length constraints) only inform.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    toRequest: (_args, token) => request("GET", "/api/validate", {}, void 0, token)
-  },
-  {
-    name: "publish",
-    description: "Compile and publish the whole site. Runs the validation gate first; if anything would break, it reports the problems and writes nothing.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    toRequest: (_args, token) => request("POST", "/api/publish", {}, void 0, token)
-  },
-  {
-    name: "list_pending_migrations",
-    description: "List content items whose JSON fields don't match their bound template's schema (orphan fields or missing required fields). Use this after a destructive template edit (you'll see a `stamped` record on write_file) to see what needs migrating, or any time to check site-wide drift.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    toRequest: (_args, token) => request("GET", "/api/migrations", {}, void 0, token)
-  },
-  {
-    name: "preview_migration",
-    description: 'For one content item, return the current template HTML, the best-fit snapshot HTML (the "before"), the list of orphan fields with their values, and the names of fields the current template defines. Use this to plan how to migrate (drop, rename, or keep each orphan).',
-    inputSchema: {
-      type: "object",
-      properties: { path: pathArg },
-      required: ["path"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request("GET", "/api/migrations/preview", { path: str(args, "path") }, void 0, token)
-  },
-  {
-    name: "apply_migration",
-    description: "Resolve a content item's schema drift in one go. `resolution` is a JSON object: `drop` (array of orphan field names to delete), `rename` (object mapping orphan field name \u2192 current template field name to copy the value into), `keep` (array of orphan field names to leave untouched), and `fill` (object mapping current template field name \u2192 value, for missing required fields). Returns the refreshed pending list.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: pathArg,
-        resolution: {
-          type: "string",
-          description: 'A JSON object encoded as a string: { "drop": string[], "rename": { from: to }, "keep": string[], "fill": { name: value } }.'
-        }
-      },
-      required: ["path", "resolution"],
-      additionalProperties: false
-    },
-    toRequest: (args, token) => request(
-      "POST",
-      "/api/migrations/apply",
-      {},
-      JSON.stringify({
-        path: str(args, "path"),
-        resolution: parseResolutionArg(str(args, "resolution"))
-      }),
-      token
-    )
-  }
-];
-function parseResolutionArg(raw) {
-  if (raw === "") return {};
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return {};
-  }
-}
-var MCP_TOOLS = TOOL_SPECS.map(
-  ({ name, description, inputSchema }) => ({ name, description, inputSchema })
-);
-function toResult(response) {
-  const text = typeof response.body === "string" ? response.body : response.body === void 0 ? "" : new TextDecoder().decode(response.body);
-  return { text, isError: response.status >= 400 };
-}
-async function callMcpTool(deps, name, args = {}, options = {}) {
-  const spec = TOOL_SPECS.find((tool) => tool.name === name);
-  if (spec === void 0) return { text: `Unknown tool: ${name}`, isError: true };
-  return toResult(await handleApi(deps, spec.toRequest(args, options.token)));
-}
-var REFERENCE_URI = "nanoesis://reference";
-var MCP_RESOURCES = [
-  {
-    uri: REFERENCE_URI,
-    name: "nanoesis authoring reference",
-    description: "The generated reference for nanoesis templates and content: tokens, field types, annotations, loops, components, and the document shell. Read this before writing templates or content.",
-    mimeType: "text/markdown"
-  }
-];
-function readMcpResource(uri) {
-  if (uri === REFERENCE_URI) {
-    return { text: renderReferenceMarkdown(buildAuthoringReference()), mimeType: "text/markdown" };
-  }
-  return void 0;
-}
-
 // ../editor-api/src/diagnose.ts
 function buildDefaultDiagnostics() {
   const registry = createDiagnosticRegistry();
@@ -1101,8 +907,313 @@ async function anyPublishedContentItem(store, dir = "content") {
   return false;
 }
 
+// ../editor-api/src/create-editor.ts
+function asSink(storage) {
+  const encoder = new TextEncoder();
+  return {
+    write: (path, contents) => storage.put(path, typeof contents === "string" ? encoder.encode(contents) : contents)
+  };
+}
+function createEditor(config) {
+  const working = new IndexedStore(config.editorFiles);
+  const sink = asSink(config.website);
+  const wipeBeforePublish = config.wipeBeforePublish ?? true;
+  const reconcile = config.enumerate === void 0 ? void 0 : async () => working.reconcile([...await config.enumerate()]);
+  const publish = async () => {
+    const validation = await validateSite(working);
+    if (validation.ok && wipeBeforePublish && config.website.wipe !== void 0) {
+      await config.website.wipe();
+    }
+    const dir = config.users === void 0 ? void 0 : authorDirectory(await config.users());
+    const prebuild = typeof config.prebuild === "function" ? await config.prebuild() : config.prebuild;
+    return publishSite(working, sink, {
+      ...config.images !== void 0 && { imageEncoder: config.images },
+      ...config.purge !== void 0 && { purge: config.purge },
+      ...config.baseUrl !== void 0 && { baseUrl: config.baseUrl },
+      ...dir !== void 0 && { authorDirectory: dir },
+      ...prebuild !== void 0 && { prebuild }
+    });
+  };
+  const users = config.users;
+  const deps = {
+    store: working,
+    identity: config.login,
+    publish,
+    diagnostics: config.diagnostics ?? buildDefaultDiagnostics(),
+    ...reconcile !== void 0 && { reconcile },
+    ...config.authEndpoints !== void 0 && { authEndpoints: config.authEndpoints },
+    ...config.userAdmin !== void 0 && { userAdmin: config.userAdmin },
+    ...config.branding !== void 0 && { branding: config.branding },
+    ...users !== void 0 && { authors: async () => authorOptions(await users()) }
+  };
+  return {
+    handleApi: (req) => handleApi(deps, req),
+    publish,
+    store: working,
+    deps
+  };
+}
+function devNoAuth() {
+  console.warn(
+    "[nanoesis] devNoAuth(): every request is treated as an admin. Do not use in production."
+  );
+  return {
+    authenticate: async () => ({
+      userId: "dev",
+      username: "dev",
+      roles: ["author", "developer", "admin"]
+    })
+  };
+}
+
+// ../editor-api/src/serve-asset.ts
+import { readFile } from "fs/promises";
+import { resolve, sep } from "path";
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8"
+};
+function mimeFor(path) {
+  const dot = path.lastIndexOf(".");
+  return dot < 0 ? "application/octet-stream" : MIME[path.slice(dot).toLowerCase()] ?? "application/octet-stream";
+}
+async function serveEditorAsset(distDir, pathname, options = {}) {
+  if (pathname === "/config.json" && options.config !== void 0) {
+    return {
+      status: 200,
+      headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+      body: JSON.stringify(options.config)
+    };
+  }
+  const base = resolve(distDir);
+  const requested = pathname === "/" || pathname === "" ? "/index.html" : pathname;
+  const filePath = resolve(base, requested.replace(/^\/+/, ""));
+  if (filePath !== base && !filePath.startsWith(base + sep)) {
+    return { status: 403, headers: { "content-type": "text/plain" }, body: "Forbidden" };
+  }
+  try {
+    const bytes = new Uint8Array(await readFile(filePath));
+    return { status: 200, headers: { "content-type": mimeFor(filePath) }, body: bytes };
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const indexBytes = new Uint8Array(await readFile(resolve(base, "index.html")));
+    return {
+      status: 200,
+      headers: { "content-type": "text/html; charset=utf-8" },
+      body: indexBytes
+    };
+  }
+}
+
+// ../editor-api/src/mcp.ts
+function str(args, key) {
+  const value = args[key];
+  return typeof value === "string" ? value : "";
+}
+function request(method, path, query, bodyText, token) {
+  const body = bodyText === void 0 ? new Uint8Array() : new TextEncoder().encode(bodyText);
+  return {
+    method,
+    path,
+    query: new URLSearchParams(query),
+    getHeader: (name) => name.toLowerCase() === "authorization" && token !== void 0 ? `Bearer ${token}` : void 0,
+    body: async () => body
+  };
+}
+var pathArg = {
+  type: "string",
+  description: 'Site-relative path with forward slashes, e.g. "content/blog/post.json".'
+};
+var TOOL_SPECS = [
+  {
+    name: "list_dir",
+    description: "List the immediate children (files and folders) of a site directory. Use '' or omit for the site root; the top-level folders are content/ (pages), templates/, components/, and public/.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path, '' for the site root." }
+      },
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("GET", "/api/list", { dir: str(args, "path") }, void 0, token)
+  },
+  {
+    name: "read_file",
+    description: "Read a file's text contents (content JSON, a template/component's HTML, CSS, etc.). Reports an error if the file does not exist.",
+    inputSchema: {
+      type: "object",
+      properties: { path: pathArg },
+      required: ["path"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("GET", "/api/read", { path: str(args, "path") }, void 0, token)
+  },
+  {
+    name: "describe_template",
+    description: "List the fields a template defines (name, type, label, whether required, length limits), so you know what a page using it needs. Pass the template name without its path or extension, e.g. 'article' for templates/article.html.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: 'Template name without path or extension, e.g. "article".'
+        }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("GET", "/api/template-fields", { name: str(args, "name") }, void 0, token)
+  },
+  {
+    name: "write_file",
+    description: "Create or overwrite a text file. content/ requires the author role; templates/, components/, and public/ require the developer role. Read the nanoesis://reference resource first for the authoring syntax. For template/component paths the response includes `schemaDelta` (added/removed/typeChanged fields) \u2014 if `typeChanged` contains `destructive: true` or `removed` is non-empty, an auto-stamp has been written and authored content may need migration, so surface to the user before further edits. For content/*.json writes the response may include `parseDiagnostics.unknownTopLevelKeys` \u2014 top-level keys the parser dropped because they are not system keys; content values belong under `fields` (system keys are case-sensitive: `isPublished`, not `IsPublished`). See the reference's 'Authoring guardrails for LLMs' section for the common pitfalls (notably: `data-*` annotations bind to the element, not the token inside it \u2014 moving a token out of its annotated container silently strips them).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: pathArg,
+        contents: { type: "string", description: "The full new text contents of the file." }
+      },
+      required: ["path", "contents"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("POST", "/api/write", { path: str(args, "path") }, str(args, "contents"), token)
+  },
+  {
+    name: "delete_path",
+    description: "Delete a file or a whole folder subtree. Same role rules as write_file. Deleting a path that does not exist is a no-op.",
+    inputSchema: {
+      type: "object",
+      properties: { path: pathArg },
+      required: ["path"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("POST", "/api/delete", { path: str(args, "path") }, void 0, token)
+  },
+  {
+    name: "rename_path",
+    description: "Move or rename a file or folder subtree. Refuses to overwrite an existing destination. Requires write rights at both the source and the destination. Renaming a template also requires updating every content item bound to the old name (the validation gate will catch unbound items on publish, but `list_pending_migrations` is the cheaper check).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "The current path." },
+        to: { type: "string", description: "The new path." }
+      },
+      required: ["from", "to"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request(
+      "POST",
+      "/api/rename",
+      { from: str(args, "from"), to: str(args, "to") },
+      void 0,
+      token
+    )
+  },
+  {
+    name: "validate",
+    description: "Run the validation gate over the whole site and return its diagnostics, without publishing. Use it to check your work: errors would block a publish, warnings (e.g. length constraints) only inform.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    toRequest: (_args, token) => request("GET", "/api/validate", {}, void 0, token)
+  },
+  {
+    name: "publish",
+    description: "Compile and publish the whole site. Runs the validation gate first; if anything would break, it reports the problems and writes nothing.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    toRequest: (_args, token) => request("POST", "/api/publish", {}, void 0, token)
+  },
+  {
+    name: "list_pending_migrations",
+    description: "List content items whose JSON fields don't match their bound template's schema (orphan fields or missing required fields). Use this after a destructive template edit (you'll see a `stamped` record on write_file) to see what needs migrating, or any time to check site-wide drift.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    toRequest: (_args, token) => request("GET", "/api/migrations", {}, void 0, token)
+  },
+  {
+    name: "preview_migration",
+    description: 'For one content item, return the current template HTML, the best-fit snapshot HTML (the "before"), the list of orphan fields with their values, and the names of fields the current template defines. Use this to plan how to migrate (drop, rename, or keep each orphan).',
+    inputSchema: {
+      type: "object",
+      properties: { path: pathArg },
+      required: ["path"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("GET", "/api/migrations/preview", { path: str(args, "path") }, void 0, token)
+  },
+  {
+    name: "apply_migration",
+    description: "Resolve a content item's schema drift in one go. `resolution` is a JSON object: `drop` (array of orphan field names to delete), `rename` (object mapping orphan field name \u2192 current template field name to copy the value into), `keep` (array of orphan field names to leave untouched), and `fill` (object mapping current template field name \u2192 value, for missing required fields). Returns the refreshed pending list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: pathArg,
+        resolution: {
+          type: "string",
+          description: 'A JSON object encoded as a string: { "drop": string[], "rename": { from: to }, "keep": string[], "fill": { name: value } }.'
+        }
+      },
+      required: ["path", "resolution"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request(
+      "POST",
+      "/api/migrations/apply",
+      {},
+      JSON.stringify({
+        path: str(args, "path"),
+        resolution: parseResolutionArg(str(args, "resolution"))
+      }),
+      token
+    )
+  }
+];
+function parseResolutionArg(raw) {
+  if (raw === "") return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+var MCP_TOOLS = TOOL_SPECS.map(
+  ({ name, description, inputSchema }) => ({ name, description, inputSchema })
+);
+function toResult(response) {
+  const text = typeof response.body === "string" ? response.body : response.body === void 0 ? "" : new TextDecoder().decode(response.body);
+  return { text, isError: response.status >= 400 };
+}
+async function callMcpTool(deps, name, args = {}, options = {}) {
+  const spec = TOOL_SPECS.find((tool) => tool.name === name);
+  if (spec === void 0) return { text: `Unknown tool: ${name}`, isError: true };
+  return toResult(await handleApi(deps, spec.toRequest(args, options.token)));
+}
+var REFERENCE_URI = "nanoesis://reference";
+var MCP_RESOURCES = [
+  {
+    uri: REFERENCE_URI,
+    name: "nanoesis authoring reference",
+    description: "The generated reference for nanoesis templates and content: tokens, field types, annotations, loops, components, and the document shell. Read this before writing templates or content.",
+    mimeType: "text/markdown"
+  }
+];
+function readMcpResource(uri) {
+  if (uri === REFERENCE_URI) {
+    return { text: renderReferenceMarkdown(buildAuthoringReference()), mimeType: "text/markdown" };
+  }
+  return void 0;
+}
+
 // ../editor-api/src/branding.ts
-import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { mkdir, readFile as readFile2, rename, rm, writeFile } from "fs/promises";
 import { dirname, join } from "path";
 var EMPTY = { name: null, logo: null };
 var InMemoryBrandingStore = class {
@@ -1144,7 +1255,7 @@ var FileBrandingStore = class {
   logoPath;
   async loadMeta() {
     try {
-      const raw = await readFile(this.metaPath, "utf8");
+      const raw = await readFile2(this.metaPath, "utf8");
       const text = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
       const parsed = JSON.parse(text);
       return {
@@ -1172,7 +1283,7 @@ var FileBrandingStore = class {
     const meta = await this.loadMeta();
     if (meta.logo === null) return null;
     try {
-      const bytes = await readFile(this.logoPath);
+      const bytes = await readFile2(this.logoPath);
       return { bytes: new Uint8Array(bytes), contentType: meta.logo.contentType };
     } catch (error) {
       if (error.code === "ENOENT") return null;
@@ -1203,10 +1314,6 @@ export {
   handleApi,
   authorOptions,
   authorDirectory,
-  MCP_TOOLS,
-  callMcpTool,
-  MCP_RESOURCES,
-  readMcpResource,
   buildDefaultDiagnostics,
   homeTemplateMissingDiagnostic,
   recreateHomeTemplateRepair,
@@ -1216,6 +1323,13 @@ export {
   templateSuffixConflictDiagnostic,
   copySnapshotToCurrentRepair,
   pendingMigrationsDiagnostic,
+  createEditor,
+  devNoAuth,
+  serveEditorAsset,
+  MCP_TOOLS,
+  callMcpTool,
+  MCP_RESOURCES,
+  readMcpResource,
   InMemoryBrandingStore,
   FileBrandingStore
 };

package/dist/editor-api.d.ts

@@ -1,4 +1,5 @@
-import { WorkingStore, IdentityProvider, PublishResult, ReconcileResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, DiagnosticRegistry, UserSummary, AuthorDirectory, Repair, DiagnosticCheck } from '@nanoesis/engine';
+import { WorkingStore, IdentityProvider, PublishResult, ReconcileResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, DiagnosticRegistry, Storage, ImageEncoder, PurgeService, UserSummary, PreBuildHook, AuthorDirectory, Repair, DiagnosticCheck } from '@nanoesis/engine';
+export { Storage } from '@nanoesis/engine';
 
 /**
  * Editor white-labelling storage (DESIGN §11, Phase B). This is the *editor app's*
@@ -158,6 +159,105 @@ interface ApiDeps {
  */
 declare function handleApi(deps: ApiDeps, req: ApiRequest): Promise<ApiResponse>;
 
+/** Everything {@link createEditor} needs. Three things are required; the rest light up features. */
+interface EditorConfig {
+    /** Where the editor reads and writes your editable files (content, templates, assets). */
+    readonly editorFiles: Storage;
+    /** Where the built website is written on publish (your live site, a folder, a CDN origin). */
+    readonly website: Storage;
+    /** Who may edit. Use {@link devNoAuth} locally; swap for a real provider in production. */
+    readonly login: IdentityProvider;
+    /**
+     * Optional full key scan of `editorFiles`. When supplied, the editor can self-heal its
+     * content index (`POST /api/reconcile`) and warn about files that bypassed it. Pass the
+     * adapter's native listing (e.g. an Azure container's `list`); omit on a store that
+     * cannot enumerate.
+     */
+    readonly enumerate?: () => Promise<readonly string[]>;
+    /** Turns `<img>` into responsive `<picture>` (AVIF/WebP/JPG). Pass the sharp adapter. */
+    readonly images?: ImageEncoder;
+    /** Clears a CDN cache after a successful publish. */
+    readonly purge?: PurgeService;
+    /** Absolute site URL; enables `sitemap.xml` and absolute links. */
+    readonly baseUrl?: string;
+    /** The users a byline may name (DESIGN §6.11): powers the authors picker and bylines. */
+    readonly users?: () => Promise<readonly UserSummary[]>;
+    /** Editor white-labelling (name + logo). */
+    readonly branding?: BrandingStore;
+    /** Credential routes (login/refresh/logout); omit for trusted-header / gateway auth. */
+    readonly authEndpoints?: AuthEndpoints;
+    /** Admin user-management routes; omit when users are managed upstream. */
+    readonly userAdmin?: UserAdminEndpoints;
+    /**
+     * A build step (Tailwind, esbuild, …) run before each publish. Pass a {@link PreBuildHook}
+     * for a fixed command, or a function resolved on every publish so a host can pick up a
+     * site's build-command change without a restart.
+     */
+    readonly prebuild?: PreBuildHook | (() => Promise<PreBuildHook | undefined>);
+    /** Admin diagnostics/self-heal; defaults to {@link buildDefaultDiagnostics}. */
+    readonly diagnostics?: DiagnosticRegistry;
+    /** Clear the website before republishing (default true). Needs `website.wipe`. */
+    readonly wipeBeforePublish?: boolean;
+}
+/** A wired editor: mount {@link handleApi} at `/api/*` and call {@link publish} to go live. */
+interface Editor {
+    /** Handle one editor API request. Mount at `/api/*` in your HTTP server. */
+    handleApi(req: ApiRequest): Promise<ApiResponse>;
+    /** Validate, then (optionally wipe and) build the site into the website store. */
+    publish(): Promise<PublishResult>;
+    /** The underlying working store, for advanced hosts that need direct access. */
+    readonly store: WorkingStore;
+    /**
+     * The assembled {@link ApiDeps}, an escape hatch for advanced transports (e.g. the MCP
+     * server) that dispatch through the dependencies directly rather than via `handleApi`.
+     * Most hosts ignore this.
+     */
+    readonly deps: ApiDeps;
+}
+/**
+ * Wire a complete nanoesis editor from a storage pair, a login, and a few optional
+ * capabilities. This is the whole integration surface (DESIGN §11c): everything that used
+ * to be hand-assembled per host, the content index over the store, the publish source/sink,
+ * index reconcile, the wipe-before-publish, and the {@link ApiDeps} bag, is built here, so
+ * internals (`IndexedStore`, `ArtifactSink`, reconcile plumbing) never reach the adopter.
+ *
+ * `publish()` validates **before** it wipes: an invalid site returns its errors and never
+ * touches the live files, so a failed publish can never blank the website (the footgun the
+ * old "host wipes, then publishes" wiring carried).
+ */
+declare function createEditor(config: EditorConfig): Editor;
+/**
+ * An {@link IdentityProvider} that treats every request as a full admin, no login. For
+ * **local development only**, it prints a warning on use. Swap for a real provider (e.g.
+ * `@nanoesis/adapter-local-jwt`) before exposing the editor to anyone.
+ */
+declare function devNoAuth(): IdentityProvider;
+
+/** A transport-agnostic response: a host maps this onto its own framework's response. */
+interface AssetResponse {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body: Uint8Array | string;
+}
+/** Options for {@link serveEditorAsset}. */
+interface ServeEditorOptions {
+    /**
+     * Served verbatim as `/config.json` (JSON, never cached). The editor SPA fetches this at
+     * boot to learn its API base URL, e.g. `{ apiUrl: 'https://editor.example.com' }`. Omit
+     * for a same-origin host where the SPA and API share a domain.
+     */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Serve one request for the bundled editor SPA from `distDir` (the `editorDist` shipped in
+ * `@xtrable-ltd/nanoesis`). Returns the requested file, or falls back to `index.html` for
+ * any unknown path so the editor's client-side router takes over (DESIGN §11c). Mount it on
+ * every non-`/api/*` GET. A path that escapes `distDir` is refused (403).
+ *
+ * This is the SPA-serving glue every host used to hand-write; one helper replaces it.
+ */
+declare function serveEditorAsset(distDir: string, pathname: string, options?: ServeEditorOptions): Promise<AssetResponse>;
+
 /** The byline picker's options, display name + stable handle, sorted by display name. */
 declare function authorOptions(users: readonly UserSummary[]): AuthorOption[];
 /**
@@ -323,4 +423,4 @@ declare const copySnapshotToCurrentRepair: Repair;
  */
 declare const pendingMigrationsDiagnostic: DiagnosticCheck;
 
-export { type ApiDeps, type ApiRequest, type ApiResponse, type BrandingLogo, type BrandingLogoMeta, type BrandingState, type BrandingStore, FileBrandingStore, InMemoryBrandingStore, MCP_RESOURCES, MCP_TOOLS, type McpCallOptions, type McpResourceDef, type McpToolDef, type McpToolResult, SCAFFOLD_FILES, authorDirectory, authorOptions, buildDefaultDiagnostics, callMcpTool, copySnapshotToCurrentRepair, handleApi, homeTemplateMissingDiagnostic, noPublishedContentDiagnostic, pendingMigrationsDiagnostic, readMcpResource, rebindItemToCurrentRepair, recreateHomeTemplateRepair, templateSnapshotIntegrityDiagnostic, templateSuffixConflictDiagnostic };
+export { type ApiDeps, type ApiRequest, type ApiResponse, type AssetResponse, type BrandingLogo, type BrandingLogoMeta, type BrandingState, type BrandingStore, type Editor, type EditorConfig, FileBrandingStore, InMemoryBrandingStore, MCP_RESOURCES, MCP_TOOLS, type McpCallOptions, type McpResourceDef, type McpToolDef, type McpToolResult, SCAFFOLD_FILES, type ServeEditorOptions, authorDirectory, authorOptions, buildDefaultDiagnostics, callMcpTool, copySnapshotToCurrentRepair, createEditor, devNoAuth, handleApi, homeTemplateMissingDiagnostic, noPublishedContentDiagnostic, pendingMigrationsDiagnostic, readMcpResource, rebindItemToCurrentRepair, recreateHomeTemplateRepair, serveEditorAsset, templateSnapshotIntegrityDiagnostic, templateSuffixConflictDiagnostic };

package/dist/editor-api.js

@@ -9,6 +9,8 @@ import {
   buildDefaultDiagnostics,
   callMcpTool,
   copySnapshotToCurrentRepair,
+  createEditor,
+  devNoAuth,
   handleApi,
   homeTemplateMissingDiagnostic,
   noPublishedContentDiagnostic,
@@ -16,9 +18,10 @@ import {
   readMcpResource,
   rebindItemToCurrentRepair,
   recreateHomeTemplateRepair,
+  serveEditorAsset,
   templateSnapshotIntegrityDiagnostic,
   templateSuffixConflictDiagnostic
-} from "./chunk-26VCV3IE.js";
+} from "./chunk-SHGYQTZ7.js";
 import "./chunk-WHK3SBV7.js";
 export {
   FileBrandingStore,
@@ -31,6 +34,8 @@ export {
   buildDefaultDiagnostics,
   callMcpTool,
   copySnapshotToCurrentRepair,
+  createEditor,
+  devNoAuth,
   handleApi,
   homeTemplateMissingDiagnostic,
   noPublishedContentDiagnostic,
@@ -38,6 +43,7 @@ export {
   readMcpResource,
   rebindItemToCurrentRepair,
   recreateHomeTemplateRepair,
+  serveEditorAsset,
   templateSnapshotIntegrityDiagnostic,
   templateSuffixConflictDiagnostic
 };

package/dist/index.d.ts

@@ -154,6 +154,22 @@ interface BlobStore {
     /** Remove `key`. Deleting an absent key is a no-op (idempotent). */
     delete(key: string): Promise<void>;
 }
+/**
+ * The single storage contract an adopter implements (DESIGN §11c): a {@link BlobStore}
+ * (get/put/delete) plus an optional {@link wipe}. The same shape backs both the editor's
+ * working files and the published website, so there is one interface to learn, not a
+ * separate read port and write sink. `createEditor` (in `@nanoesis/editor-api`) consumes
+ * this; the ready-made adapters (e.g. `folderStorage`) implement it, so most adopters write
+ * none of it.
+ */
+interface Storage extends BlobStore {
+    /**
+     * Optional: remove everything in the store. Used to clear the previous publish before
+     * re-emitting the website, so deleted pages disappear. A store that cannot enumerate
+     * (and so cannot clear itself) omits it; the publish then only overwrites.
+     */
+    wipe?(): Promise<void>;
+}
 /**
  * In-memory {@link BlobStore} backed by a plain map, the test double the engine's
  * store and index tests run against (the LSP guarantee that real adapters are
@@ -1698,4 +1714,4 @@ declare function createDiagnosticRegistry(): DiagnosticRegistry;
 
 declare const workingStoreRoundTripDiagnostic: Diagnostic;
 
-export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type MigrationResolution, type PageEntry, type PendingMigrationItem, type PendingMigrations, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type RepairArgs, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type SchemaDelta, type SchemaFieldRef, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type StampDecision, type StampRecord, type TemplateAnalysis, type TemplateKind, type TokenContext, type TokenRef, type TreeNode, type TypeChange, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, applyMigration, baseTemplateName, bestFitSnapshot, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, computeSchemaDelta, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, detectStamp, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isDestructiveTypeChange, isFieldType, isReservedVersionedPath, isVersionedTemplateName, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, nextVersionNumber, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, pendingMigrations, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, snapshotName, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, versionNumber, wholeValueToken, workingStoreRoundTripDiagnostic };
+export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type MigrationResolution, type PageEntry, type PendingMigrationItem, type PendingMigrations, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type RepairArgs, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type SchemaDelta, type SchemaFieldRef, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type StampDecision, type StampRecord, type Storage, type TemplateAnalysis, type TemplateKind, type TokenContext, type TokenRef, type TreeNode, type TypeChange, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, applyMigration, baseTemplateName, bestFitSnapshot, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, computeSchemaDelta, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, detectStamp, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isDestructiveTypeChange, isFieldType, isReservedVersionedPath, isVersionedTemplateName, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, nextVersionNumber, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, pendingMigrations, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, snapshotName, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, versionNumber, wholeValueToken, workingStoreRoundTripDiagnostic };

package/dist/mcp.js

@@ -3,7 +3,7 @@ import {
   MCP_TOOLS,
   callMcpTool,
   readMcpResource
-} from "./chunk-26VCV3IE.js";
+} from "./chunk-SHGYQTZ7.js";
 import "./chunk-WHK3SBV7.js";
 
 // ../../hosts/host-mcp/src/http.ts
@@ -56,7 +56,7 @@ function createMcpServer(deps, identity) {
 }
 
 // ../../hosts/host-mcp/src/http.ts
-var DEFAULT_VERSION = true ? "0.1.21" : "0.0.0-workspace";
+var DEFAULT_VERSION = true ? "0.1.22" : "0.0.0-workspace";
 async function handleMcpRequest(deps, request, opts) {
   const server = createMcpServer(deps, {
     name: opts?.name ?? "nanoesis",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrable-ltd/nanoesis",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "nanoesis: a static-first publishing compiler. The engine, the mountable editor API, the storage/image/auth adapters, and the editor UI bundle, in one package (DESIGN 11c).",
   "license": "MIT",
   "author": "Xtrable Ltd",