@xtrable-ltd/nanoesis 0.1.32 → 0.1.34

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

@@ -23,11 +23,23 @@ interface BlobContainer {
     /**
      * Create or overwrite a blob with the given bytes and content type. `cacheControl`, when
      * given, is stored as the blob's `Cache-Control` so a static-website read serves the right
-     * freshness (DESIGN §11); omitted for the editor's working blobs.
+     * freshness (DESIGN §11); omitted for the editor's working blobs. `hash`, when given, is
+     * stored as blob metadata (`nanohash`) so a later publish can tell whether the content is
+     * unchanged and skip the upload (see docs/change-detection-on-publish.md); a write *without*
+     * a `hash` clears any prior stored hash, matching Azure's overwrite-replaces-metadata
+     * semantics, so a stale hash can never outlive the bytes it described.
      */
-    write(name: string, data: Uint8Array, contentType: string, cacheControl?: string): Promise<void>;
+    write(name: string, data: Uint8Array, contentType: string, cacheControl?: string, hash?: string): Promise<void>;
     /** Delete a blob; a missing blob is a no-op (idempotent). */
     remove(name: string): Promise<void>;
+    /**
+     * Every blob name beginning with `prefix` mapped to its stored content hash (the `nanohash`
+     * metadata, `undefined` for a blob written without one), for change detection on publish.
+     * Reads metadata from the same listing as {@link list} (one round trip, no blob bodies), so
+     * a host can diff a candidate artifact's hash against what is live and skip an unchanged
+     * upload. Sorted by name, like {@link list}, to keep any downstream walk deterministic.
+     */
+    listWithHashes(prefix: string): Promise<ReadonlyMap<string, string | undefined>>;
     /**
      * A blob's bytes plus its current version tag (the Azure ETag), or null if absent. Pairs
      * with {@link writeConditional} for the optimistic-concurrency the content index needs
@@ -53,6 +65,8 @@ interface BlobContainer {
 declare class InMemoryBlobContainer implements BlobContainer {
     private readonly blobs;
     private readonly cacheControls;
+    /** Per-blob `nanohash` metadata, the in-memory stand-in for the real blob metadata. */
+    private readonly hashes;
     /** Per-blob version, bumped on every write, the in-memory stand-in for an ETag. */
     private readonly versions;
     private nextVersion;
@@ -60,8 +74,9 @@ declare class InMemoryBlobContainer implements BlobContainer {
     private store;
     list(prefix: string): Promise<readonly string[]>;
     read(name: string): Promise<Uint8Array | null>;
-    write(name: string, data: Uint8Array, contentType?: string, cacheControl?: string): Promise<void>;
+    write(name: string, data: Uint8Array, contentType?: string, cacheControl?: string, hash?: string): Promise<void>;
     remove(name: string): Promise<void>;
+    listWithHashes(prefix: string): Promise<ReadonlyMap<string, string | undefined>>;
     readVersioned(name: string): Promise<{
         bytes: Uint8Array;
         version: string;
@@ -71,6 +86,8 @@ declare class InMemoryBlobContainer implements BlobContainer {
     get names(): readonly string[];
     /** Test helper: the `Cache-Control` a blob was written with, if any. */
     cacheControlOf(name: string): string | undefined;
+    /** Test helper: the `nanohash` metadata a blob was written with, if any. */
+    hashOf(name: string): string | undefined;
 }
 
 /**
@@ -88,8 +105,9 @@ declare class AzureBlobContainer implements BlobContainer {
     /** Create the container if it does not exist (idempotent host start-up step). */
     ensureContainer(): Promise<void>;
     list(prefix: string): Promise<readonly string[]>;
+    listWithHashes(prefix: string): Promise<ReadonlyMap<string, string | undefined>>;
     read(name: string): Promise<Uint8Array | null>;
-    write(name: string, data: Uint8Array, contentType: string, cacheControl?: string): Promise<void>;
+    write(name: string, data: Uint8Array, contentType: string, cacheControl?: string, hash?: string): Promise<void>;
     remove(name: string): Promise<void>;
     readVersioned(name: string): Promise<{
         bytes: Uint8Array;
@@ -133,14 +151,31 @@ declare class BlobArtifactSink implements ArtifactSink {
     write(path: string, contents: string | Uint8Array, cacheControl?: string): Promise<void>;
 }
 
+/** Options for {@link azureStorage}. */
+interface AzureStorageOptions {
+    /**
+     * Skip re-uploading a blob whose content is byte-identical to what is already stored
+     * (docs/change-detection-on-publish.md). On every `put` the store hashes the bytes and
+     * compares against the live `nanohash` metadata (read once per publish, no blob bodies);
+     * an unchanged blob is not written, a changed/new one is written and re-stamped. Default
+     * **off**, so existing behaviour (always write) is unchanged. Enable it only on the
+     * **published** container, never the working store, whose conditional index writes must
+     * not be skipped.
+     */
+    readonly changeDetection?: boolean;
+}
 /**
  * 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`
+ * {@link BlobContainerStore}) plus `wipe` (delete every blob) and `prune` (delete every blob
+ * not in a keep set, the zero-downtime publish sweep). 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.
+ *
+ * Pass `{ changeDetection: true }` on the **published** container to skip uploads of unchanged
+ * blobs (see {@link AzureStorageOptions.changeDetection}).
  */
-declare function azureStorage(container: BlobContainer): Storage & ConditionalBlobStore;
+declare function azureStorage(container: BlobContainer, options?: AzureStorageOptions): Storage & ConditionalBlobStore;
 
 /**
  * Pure path/name helper for the blob adapters. Blob storage is a *flat* namespace, a blob

package/dist/adapter-azure-blob.js

@@ -1,11 +1,14 @@
 import {
+  contentHash,
   contentTypeFor
-} from "./chunk-D5G56CA4.js";
+} from "./chunk-P6NDWIKK.js";
 
 // ../../adapters/azure-blob/src/container.ts
 var InMemoryBlobContainer = class {
   blobs = /* @__PURE__ */ new Map();
   cacheControls = /* @__PURE__ */ new Map();
+  /** Per-blob `nanohash` metadata, the in-memory stand-in for the real blob metadata. */
+  hashes = /* @__PURE__ */ new Map();
   /** Per-blob version, bumped on every write, the in-memory stand-in for an ETag. */
   versions = /* @__PURE__ */ new Map();
   nextVersion = 1;
@@ -31,14 +34,22 @@ var InMemoryBlobContainer = class {
   async read(name) {
     return this.blobs.get(name) ?? null;
   }
-  async write(name, data, contentType, cacheControl) {
+  async write(name, data, contentType, cacheControl, hash) {
     void contentType;
     this.store(name, data);
     if (cacheControl !== void 0) this.cacheControls.set(name, cacheControl);
+    if (hash !== void 0) this.hashes.set(name, hash);
+    else this.hashes.delete(name);
   }
   async remove(name) {
     this.blobs.delete(name);
     this.versions.delete(name);
+    this.hashes.delete(name);
+  }
+  async listWithHashes(prefix) {
+    const out = /* @__PURE__ */ new Map();
+    for (const name of await this.list(prefix)) out.set(name, this.hashes.get(name));
+    return out;
   }
   async readVersioned(name) {
     const bytes = this.blobs.get(name);
@@ -60,6 +71,10 @@ var InMemoryBlobContainer = class {
   cacheControlOf(name) {
     return this.cacheControls.get(name);
   }
+  /** Test helper: the `nanohash` metadata a blob was written with, if any. */
+  hashOf(name) {
+    return this.hashes.get(name);
+  }
 };
 
 // ../../adapters/azure-blob/src/azure-container.ts
@@ -95,6 +110,14 @@ var AzureBlobContainer = class _AzureBlobContainer {
     }
     return names.sort();
   }
+  async listWithHashes(prefix) {
+    const entries = [];
+    for await (const blob of this.client.listBlobsFlat({ prefix, includeMetadata: true })) {
+      entries.push([blob.name, blob.metadata?.["nanohash"]]);
+    }
+    entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return new Map(entries);
+  }
   async read(name) {
     try {
       const buffer = await this.client.getBlockBlobClient(name).downloadToBuffer();
@@ -104,12 +127,16 @@ var AzureBlobContainer = class _AzureBlobContainer {
       throw error;
     }
   }
-  async write(name, data, contentType, cacheControl) {
+  async write(name, data, contentType, cacheControl, hash) {
     await this.client.getBlockBlobClient(name).uploadData(Buffer.from(data), {
       blobHTTPHeaders: {
         blobContentType: contentType,
         ...cacheControl !== void 0 && { blobCacheControl: cacheControl }
-      }
+      },
+      // Stamp the content hash as metadata for change detection on the next publish. Azure
+      // lowercases metadata keys, so the key is already lowercase. An upload with no `hash`
+      // omits metadata, which (since uploadData replaces the blob) clears any prior hash.
+      ...hash !== void 0 && { metadata: { nanohash: hash } }
     });
   }
   async remove(name) {
@@ -200,23 +227,58 @@ var BlobArtifactSink = class {
 };
 
 // ../../adapters/azure-blob/src/azure-storage.ts
-function azureStorage(container) {
+function azureStorage(container, options = {}) {
   const store = new BlobContainerStore(container);
-  return {
+  const wipe = async () => {
+    for (const name of await container.list("")) await container.remove(name);
+  };
+  const prune = async (keep) => {
+    for (const name of await container.list("")) {
+      if (!keep.has(name)) await container.remove(name);
+    }
+  };
+  const common = {
     get: (key) => store.get(key),
-    // Forward `cacheControl` (DESIGN §11): this is the published-site sink `createEditor`
-    // actually wires (`asSink(azureStorage(website))`), so dropping the arg here silently
-    // strips the publish Cache-Control before it reaches the blob.
-    put: (key, bytes, cacheControl) => store.put(key, bytes, cacheControl),
     delete: (key) => store.delete(key),
     // Optimistic-concurrency capability (DESIGN §11d): surfaced so a horizontally-scaled
     // host's IndexedStore compare-and-sets the content index instead of blind-overwriting
     // it, which is what stops two instances losing each other's updates
     // (NANOESIS-MCP-ISSUES Issue 1). Azure blobs back this with native ETag conditions.
     getVersioned: (key) => store.getVersioned(key),
-    putConditional: (key, bytes, expected) => store.putConditional(key, bytes, expected),
+    putConditional: (key, bytes, expected) => store.putConditional(key, bytes, expected)
+  };
+  if (!options.changeDetection) {
+    return {
+      ...common,
+      // Forward `cacheControl` (DESIGN §11): this is the published-site sink `createEditor`
+      // actually wires (`asSink(azureStorage(website))`), so dropping the arg here silently
+      // strips the publish Cache-Control before it reaches the blob.
+      put: (key, bytes, cacheControl) => store.put(key, bytes, cacheControl),
+      wipe,
+      prune
+    };
+  }
+  let live = null;
+  const reset = () => {
+    live = null;
+  };
+  return {
+    ...common,
+    put: async (key, bytes, cacheControl) => {
+      if (live === null) live = new Map(await container.listWithHashes(""));
+      const name = normalizeBlobName(key);
+      const hash = contentHash(bytes);
+      if (live.get(name) === hash) return;
+      await container.write(name, bytes, contentTypeFor(name), cacheControl, hash);
+      live.set(name, hash);
+    },
     wipe: async () => {
-      for (const name of await container.list("")) await container.remove(name);
+      await wipe();
+      reset();
+    },
+    prune: async (keep) => {
+      await prune(keep);
+      reset();
     }
   };
 }

package/dist/{chunk-6Y3I6SYT.js → chunk-C3QPGXG5.js}

@@ -18,7 +18,7 @@ import {
   renderReferenceMarkdown,
   validateSite,
   workingStoreRoundTripDiagnostic
-} from "./chunk-D5G56CA4.js";
+} from "./chunk-P6NDWIKK.js";
 
 // ../editor-api/src/scaffold.ts
 var HOME_HTML = `<!doctype html>
@@ -949,12 +949,12 @@ function createEditor(config) {
     };
     try {
       const validation = await validateSite(working);
-      if (validation.ok && wipeBeforePublish && config.website.wipe !== void 0) {
+      if (validation.ok && wipeBeforePublish && config.website.prune === void 0 && 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 await publishSite(working, sink, {
+      const result = await publishSite(working, sink, {
         ...config.images !== void 0 && { imageEncoder: config.images },
         ...config.purge !== void 0 && { purge: config.purge },
         ...config.baseUrl !== void 0 && { baseUrl: config.baseUrl },
@@ -962,6 +962,10 @@ function createEditor(config) {
         ...prebuild !== void 0 && { prebuild },
         onProgress: record
       });
+      if (result.ok && wipeBeforePublish && config.website.prune !== void 0) {
+        await config.website.prune(new Set(result.written));
+      }
+      return result;
     } finally {
       progressRunning = false;
     }

package/dist/{chunk-D5G56CA4.js → chunk-P6NDWIKK.js}

@@ -3319,13 +3319,20 @@ async function publishSite(source, sink, options = {}) {
   );
   const byPath = /* @__PURE__ */ new Map();
   for (const artifact of [...stamped, ...passthrough]) byPath.set(artifact.path, artifact);
+  const everything = [...byPath.values()];
+  const pages = everything.filter((artifact) => artifact.path.endsWith(".html"));
+  const resources = everything.filter((artifact) => !artifact.path.endsWith(".html"));
   const uploadTotal = byPath.size;
   let uploaded = 0;
-  await mapWithConcurrency([...byPath.values()], writeConcurrency, async (artifact) => {
-    await sink.write(artifact.path, artifact.contents, cacheControlFor(artifact));
-    uploaded += 1;
-    onProgress?.({ phase: "upload", written: uploaded, total: uploadTotal });
-  });
+  const writeGroup = async (group) => {
+    await mapWithConcurrency(group, writeConcurrency, async (artifact) => {
+      await sink.write(artifact.path, artifact.contents, cacheControlFor(artifact));
+      uploaded += 1;
+      onProgress?.({ phase: "upload", written: uploaded, total: uploadTotal });
+    });
+  };
+  await writeGroup(resources);
+  await writeGroup(pages);
   if (purge !== noopPurgeService) onProgress?.({ phase: "purge" });
   await purge.purgeAll();
   onProgress?.({ phase: "done", written: uploadTotal, summary });

package/dist/editor-api.d.ts

@@ -222,7 +222,12 @@ interface EditorConfig {
     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`. */
+    /**
+     * Whether a publish clears pages the new build no longer emits (default true). A
+     * `prune`-capable website does this as a post-publish orphan sweep (overwrite-in-place,
+     * zero downtime); a wipe-only website clears up front instead. Set false to never delete
+     * (overwrite-only, stale pages linger). Names `wipeBeforePublish` for back-compat.
+     */
     readonly wipeBeforePublish?: boolean;
 }
 /** A wired editor: mount {@link handleApi} at `/api/*` and call {@link publish} to go live. */
@@ -244,12 +249,13 @@ interface Editor {
  * 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
+ * index reconcile, the orphan sweep, 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).
+ * `publish()` validates **first**: an invalid site returns its errors and never touches the
+ * live files. A `prune`-capable website then overwrites every artifact in place and sweeps
+ * the orphans afterwards, so a publish never blanks the live site, not even for the upload
+ * window (the footgun the old "host wipes, then publishes" wiring carried).
  */
 declare function createEditor(config: EditorConfig): Editor;
 /**

package/dist/editor-api.js

@@ -21,8 +21,8 @@ import {
   serveEditorAsset,
   templateSnapshotIntegrityDiagnostic,
   templateSuffixConflictDiagnostic
-} from "./chunk-6Y3I6SYT.js";
-import "./chunk-D5G56CA4.js";
+} from "./chunk-C3QPGXG5.js";
+import "./chunk-P6NDWIKK.js";
 export {
   FileBrandingStore,
   InMemoryBrandingStore,

package/dist/index.d.ts

@@ -204,6 +204,17 @@ interface Storage extends BlobStore {
      * (and so cannot clear itself) omits it; the publish then only overwrites.
      */
     wipe?(): Promise<void>;
+    /**
+     * Optional: delete every key **not** in `keep`, leaving the kept keys untouched. The
+     * zero-downtime alternative to {@link wipe} for a published website: the host overwrites
+     * every artifact in place (each key flips old→new atomically, so no URL is ever missing),
+     * then calls `prune` with the just-written path set to sweep only the orphans, pages that
+     * no longer exist. Unlike `wipe` (clear *before* the upload, blanking the live site for the
+     * whole write), `prune` runs *after* a successful upload and only removes what the new
+     * publish did not write. A store that cannot enumerate omits it; the host falls back to
+     * `wipe`, or to overwrite-only when neither is available.
+     */
+    prune?(keep: ReadonlySet<string>): Promise<void>;
 }
 /**
  * In-memory {@link BlobStore} backed by a plain map, the test double the engine's

package/dist/index.js

@@ -83,7 +83,7 @@ import {
   versionNumber,
   wholeValueToken,
   workingStoreRoundTripDiagnostic
-} from "./chunk-D5G56CA4.js";
+} from "./chunk-P6NDWIKK.js";
 export {
   CACHE_IMMUTABLE,
   CACHE_REVALIDATE,

package/dist/mcp.js

@@ -3,8 +3,8 @@ import {
   MCP_TOOLS,
   callMcpTool,
   readMcpResource
-} from "./chunk-6Y3I6SYT.js";
-import "./chunk-D5G56CA4.js";
+} from "./chunk-C3QPGXG5.js";
+import "./chunk-P6NDWIKK.js";
 
 // ../../hosts/host-mcp/src/http.ts
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -56,7 +56,7 @@ function createMcpServer(deps, identity) {
 }
 
 // ../../hosts/host-mcp/src/http.ts
-var DEFAULT_VERSION = true ? "0.1.32" : "0.0.0-workspace";
+var DEFAULT_VERSION = true ? "0.1.34" : "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.32",
+  "version": "0.1.34",
   "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",