@xtrable-ltd/nanoesis 0.1.33 → 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,6 +151,19 @@ 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) and `prune` (delete every blob
@@ -140,8 +171,11 @@ declare class BlobArtifactSink implements ArtifactSink {
  * 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,4 +1,5 @@
 import {
+  contentHash,
   contentTypeFor
 } from "./chunk-P6NDWIKK.js";
 
@@ -6,6 +7,8 @@ import {
 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,32 +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();
     },
-    // Zero-downtime sweep (DESIGN §11): the publish overwrites every artifact in place, then
-    // calls this with the just-written path set so only orphaned blobs (pages the new publish
-    // did not emit) are removed. Every live URL keeps serving throughout, the old wipe-first
-    // path blanked the whole site for the upload window.
     prune: async (keep) => {
-      for (const name of await container.list("")) {
-        if (!keep.has(name)) await container.remove(name);
-      }
+      await prune(keep);
+      reset();
     }
   };
 }

package/dist/mcp.js

@@ -56,7 +56,7 @@ function createMcpServer(deps, identity) {
 }
 
 // ../../hosts/host-mcp/src/http.ts
-var DEFAULT_VERSION = true ? "0.1.33" : "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.33",
+  "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",