@xtrable-ltd/nanoesis 0.1.0 → 0.1.2

package/dist/adapter-azure-blob.js

@@ -1,6 +1,6 @@
 import {
   contentTypeFor
-} from "./chunk-G2UEZTYC.js";
+} from "./chunk-22WHPW5E.js";
 
 // ../../adapters/azure-blob/src/container.ts
 var InMemoryBlobContainer = class {

package/dist/{chunk-G2UEZTYC.js → chunk-22WHPW5E.js}

@@ -182,6 +182,16 @@ async function saveIndex(store, prev, nextKeys) {
   await store.put(INDEX_KEY, serialize(next));
   return next;
 }
+async function reconcileIndex(store, actualKeys) {
+  const prev = await loadIndex(store);
+  const keys = [...new Set(actualKeys.filter((key) => !key.startsWith(RESERVED_PREFIX)))].sort();
+  const prevKeys = new Set(prev.keys);
+  const nextKeys = new Set(keys);
+  const added = keys.filter((key) => !prevKeys.has(key));
+  const removed = prev.keys.filter((key) => !nextKeys.has(key));
+  if (added.length === 0 && removed.length === 0) return { index: prev, added, removed };
+  return { index: await saveIndex(store, prev, keys), added, removed };
+}
 function freezeIndex(version, keys) {
   const sorted = [...new Set(keys)].sort();
   return { version, keys: sorted, checksum: checksumOf(version, sorted) };
@@ -312,6 +322,19 @@ var IndexedStore = class {
     this.index = await saveIndex(this.store, index, next);
     return { ok: true };
   }
+  /**
+   * Rebuild this store's index from the *actual* keys the underlying store holds (DESIGN
+   * §11d), recovering files that arrived by a path that bypassed the index. A
+   * {@link BlobStore} cannot enumerate itself, so the caller supplies the real key set
+   * from an adapter that can (e.g. `BlobContainer.list`). Unlike calling
+   * {@link reconcileIndex} on a fresh store, this also refreshes the cached in-memory
+   * index, so this live instance sees the recovered files immediately.
+   */
+  async reconcile(actualKeys) {
+    const result = await reconcileIndex(this.store, actualKeys);
+    this.index = result.index;
+    return result;
+  }
 };
 function guarded(key) {
   if (key === "" || key.startsWith(RESERVED_PREFIX)) {
@@ -2485,9 +2508,11 @@ export {
   parseContentItem,
   parseSortFile,
   InMemoryBlobStore,
+  RESERVED_PREFIX,
   emptyIndex,
   loadIndex,
   saveIndex,
+  reconcileIndex,
   IndexedStore,
   InMemoryContentSource,
   parseRedirects,

package/dist/editor-api.d.ts

@@ -1,4 +1,4 @@
-import { WorkingStore, IdentityProvider, PublishResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, UserSummary, AuthorDirectory } from '@nanoesis/engine';
+import { WorkingStore, IdentityProvider, PublishResult, ReconcileResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, UserSummary, AuthorDirectory } from '@nanoesis/engine';
 
 /**
  * Editor white-labelling storage (DESIGN §11, Phase B). This is the *editor app's*
@@ -100,6 +100,15 @@ interface ApiDeps {
     readonly identity: IdentityProvider;
     /** Run the publish pipeline (host binds source/sink/purge). */
     readonly publish: () => Promise<PublishResult>;
+    /**
+     * Optional index-reconcile (DESIGN §11d): rebuild the working store's content index
+     * from the keys actually present, recovering files that arrived by a path that
+     * bypassed the index (the silent-bootstrap failure). When present, the router mounts
+     * the admin-gated `POST /api/reconcile`. The host binds it because enumerating the
+     * real key set needs the adapter's listing (`BlobContainer.list`), which the engine's
+     * `BlobStore` deliberately lacks. Omitted on stores that cannot enumerate.
+     */
+    readonly reconcile?: () => Promise<ReconcileResult>;
     /**
      * Optional credential-management surface (DESIGN §11). When present, the router
      * mounts `/api/login`, `/api/refresh`, `/api/logout`, and `/api/auth/state`,
@@ -195,4 +204,25 @@ declare function readMcpResource(uri: string): {
     readonly mimeType: string;
 } | undefined;
 
-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, authorDirectory, authorOptions, callMcpTool, handleApi, readMcpResource };
+/**
+ * The first-run starter site (DESIGN §14): a minimal, self-contained set of files that
+ * turns an empty working store into a real, publishable site. It is the *blessed* way to
+ * get initial content in — written through the editor API (so the content index stays
+ * authoritative by construction, never the bypassing path that silently breaks a store,
+ * §11d) and bundled here as **pure data**, so the engine's purity is untouched and the
+ * scaffold works identically for every host and the MCP server with no per-host wiring.
+ *
+ * Deliberately minimal (the owner's call, distinct from the fuller `examples/starter`):
+ * one home page, a page template, the document shell, and a stylesheet. It is gate-clean
+ * by construction — no collection loops (nothing to point at yet), no custom components,
+ * no required fields left unset — so a fresh adopter can publish it immediately, and the
+ * home page is a **draft** (`isPublished: false`) so going live is a deliberate act.
+ */
+/**
+ * The starter files, keyed by working-store path. Written through the store's `write`
+ * (so the index records each), in this order — templates and styles before the content
+ * that depends on them, though the store has no cross-file ordering requirement.
+ */
+declare const SCAFFOLD_FILES: Readonly<Record<string, string>>;
+
+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, callMcpTool, handleApi, readMcpResource };

package/dist/editor-api.js

@@ -8,7 +8,111 @@ import {
   loadTemplate,
   renderReferenceMarkdown,
   validateSite
-} from "./chunk-G2UEZTYC.js";
+} from "./chunk-22WHPW5E.js";
+
+// ../editor-api/src/scaffold.ts
+var DOCUMENT_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    <meta name="description" content="{meta_description}" />
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <header class="site-header">
+      <a class="brand" href="/">Your site</a>
+    </header>
+    <main>
+      <slot></slot>
+    </main>
+    <footer class="site-footer">
+      <p>Built with nanoesis \u2014 static HTML, no runtime.</p>
+    </footer>
+  </body>
+</html>
+`;
+var HOME_HTML = `<section class="hero">
+  <h1>{title}</h1>
+  <p class="lead">{lead}</p>
+</section>
+<div class="prose" data-type="richtext">{body}</div>
+`;
+var HOME_JSON = `${JSON.stringify(
+  {
+    template: "home",
+    title: "Welcome",
+    isPublished: false,
+    fields: {
+      lead: "Edit this page in the nanoesis editor, then publish when you are ready.",
+      body: "<p>This is your new site. It compiles to plain static HTML \u2014 there is no server and no client framework, and nothing of the editor survives into production.</p>"
+    }
+  },
+  null,
+  2
+)}
+`;
+var STYLES_CSS = `:root {
+  --ink: #1a1a2e;
+  --muted: #555;
+  --accent: #4f46e5;
+  --max: 42rem;
+  font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  line-height: 1.6;
+  color: var(--ink);
+}
+
+body {
+  margin: 0;
+}
+
+.site-header,
+main,
+.site-footer {
+  max-width: var(--max);
+  margin-inline: auto;
+  padding: 1.5rem 1.25rem;
+}
+
+.site-header .brand {
+  font-weight: 700;
+  text-decoration: none;
+  color: var(--ink);
+}
+
+.hero h1 {
+  font-size: 2.25rem;
+  letter-spacing: -0.01em;
+  margin: 0 0 0.5rem;
+}
+
+.lead {
+  font-size: 1.2rem;
+  color: var(--muted);
+  margin: 0 0 2rem;
+}
+
+.prose {
+  font-size: 1.05rem;
+}
+
+a {
+  color: var(--accent);
+}
+
+.site-footer {
+  color: var(--muted);
+  font-size: 0.9rem;
+  border-top: 1px solid #eee;
+}
+`;
+var SCAFFOLD_FILES = {
+  "templates/document.html": DOCUMENT_HTML,
+  "templates/home.html": HOME_HTML,
+  "public/styles.css": STYLES_CSS,
+  "content/index.json": HOME_JSON
+};
 
 // ../editor-api/src/api.ts
 var MAX_LOGO_BYTES = 1024 * 1024;
@@ -283,6 +387,42 @@ async function handleApi(deps, req) {
       if (result.ok) return json(200, { ok: true, written: result.written.length });
       return json(422, { ok: false, errors: result.validation.errors.map((e) => e.message) });
     }
+    case "/api/scaffold": {
+      if (req.method !== "POST") return methodNotAllowed();
+      if (!hasRole(principal, "admin")) {
+        return json(403, { ok: false, error: "admin role required" });
+      }
+      if ((await deps.store.list("content")).length > 0) {
+        return json(409, { ok: false, error: "site already has content" });
+      }
+      const created = [];
+      const skipped = [];
+      for (const [path, content] of Object.entries(SCAFFOLD_FILES)) {
+        if (await deps.store.exists(path)) {
+          skipped.push(path);
+          continue;
+        }
+        await deps.store.write(path, new TextEncoder().encode(content));
+        created.push(path);
+      }
+      return json(200, { ok: true, created, skipped });
+    }
+    case "/api/reconcile": {
+      if (req.method !== "POST") return methodNotAllowed();
+      if (deps.reconcile === void 0) {
+        return json(404, { ok: false, error: "reconcile is not available on this host" });
+      }
+      if (!hasRole(principal, "admin")) {
+        return json(403, { ok: false, error: "admin role required" });
+      }
+      const result = await deps.reconcile();
+      return json(200, {
+        ok: true,
+        added: result.added.length,
+        removed: result.removed.length,
+        total: result.index.keys.length
+      });
+    }
     case "/api/me/password": {
       if (req.method !== "POST") return methodNotAllowed();
       if (deps.authEndpoints === void 0) {
@@ -584,6 +724,7 @@ export {
   InMemoryBrandingStore,
   MCP_RESOURCES,
   MCP_TOOLS,
+  SCAFFOLD_FILES,
   authorDirectory,
   authorOptions,
   callMcpTool,

package/dist/index.d.ts

@@ -203,6 +203,62 @@ interface WorkingStore extends ContentSource {
     rename(from: string, to: string): Promise<RenameResult>;
 }
 
+/**
+ * The content index (DESIGN §11d): the sorted set of every key in the working store,
+ * the directory listing a flat blob store cannot give cheaply, lifted into one object
+ * we own. Enumeration (the editor tree, compile) reads this, so the adopter's store
+ * stays get/put/delete with no `list`. Persisted under a reserved key with a fixed-size
+ * backup ring for integrity.
+ */
+interface ContentIndex {
+    /** Monotonic, bumped on every save; orders the backup ring during recovery. */
+    readonly version: number;
+    /** Every key that exists, sorted and de-duplicated (deterministic, CLAUDE §2). */
+    readonly keys: readonly string[];
+    /** Checksum over version + keys, so a corrupt stored index is caught on read. */
+    readonly checksum: string;
+}
+/** Reserved key prefix for the index and its backups; excluded from enumeration. */
+declare const RESERVED_PREFIX = ".nanoesis/";
+/** The empty index of a fresh store: version 0, no keys. */
+declare function emptyIndex(): ContentIndex;
+/**
+ * Load the index, recovering through the backup ring if the live copy is missing or
+ * corrupt (DESIGN §11d): the highest valid version among the ring slots wins. Returns
+ * the empty index when nothing valid is found, a fresh store, or the accepted residual
+ * case where the live index and every backup are lost (the files still exist by key,
+ * but cannot be enumerated until something rewrites the index).
+ */
+declare function loadIndex(store: BlobStore): Promise<ContentIndex>;
+/**
+ * Write a new index whose keys are `nextKeys`, backing up the one it replaces first
+ * (DESIGN §11d). The previous index goes into its ring slot (`version % ring`, oldest
+ * overwritten), then the new index is written to the live key, a constant two writes
+ * per save regardless of ring size. Returns the new index (the caller's next `prev`).
+ */
+declare function saveIndex(store: BlobStore, prev: ContentIndex, nextKeys: readonly string[]): Promise<ContentIndex>;
+/** What a {@link reconcileIndex} did, for a maintenance UI/CLI and the startup signal. */
+interface ReconcileResult {
+    /** The index after reconciling (the prior one unchanged when nothing differed). */
+    readonly index: ContentIndex;
+    /** Keys now in the index that the prior index lacked (orphaned blobs, recovered). */
+    readonly added: readonly string[];
+    /** Keys the prior index held that no longer exist in the store (stale entries dropped). */
+    readonly removed: readonly string[];
+}
+/**
+ * Rebuild the index from the store's *actual* keys (DESIGN §11d): the safety net for a
+ * store that got files by a path that bypassed the index, where the files are present
+ * by key but unenumerable. The engine cannot list a {@link BlobStore} (none is required
+ * to, §11c), so the caller supplies the real key set, an adapter that *can* enumerate
+ * (e.g. `BlobContainer.list`) provides it; the rebuild stays pure index logic here.
+ *
+ * The reserved namespace is never indexed (the index is not its own content). When the
+ * resulting key set matches the existing index this is a no-op, no write, no version
+ * bump, so reconciling a healthy store is cheap and idempotent.
+ */
+declare function reconcileIndex(store: BlobStore, actualKeys: readonly string[]): Promise<ReconcileResult>;
+
 /**
  * A {@link ContentSource} backed by the content index (DESIGN §11d) over a
  * {@link BlobStore}: enumeration (`list`/`exists`) is synthesised from the index's key
@@ -251,41 +307,17 @@ declare class IndexedStore implements WorkingStore {
      * still throws.)
      */
     rename(from: string, to: string): Promise<RenameResult>;
+    /**
+     * Rebuild this store's index from the *actual* keys the underlying store holds (DESIGN
+     * §11d), recovering files that arrived by a path that bypassed the index. A
+     * {@link BlobStore} cannot enumerate itself, so the caller supplies the real key set
+     * from an adapter that can (e.g. `BlobContainer.list`). Unlike calling
+     * {@link reconcileIndex} on a fresh store, this also refreshes the cached in-memory
+     * index, so this live instance sees the recovered files immediately.
+     */
+    reconcile(actualKeys: readonly string[]): Promise<ReconcileResult>;
 }
 
-/**
- * The content index (DESIGN §11d): the sorted set of every key in the working store,
- * the directory listing a flat blob store cannot give cheaply, lifted into one object
- * we own. Enumeration (the editor tree, compile) reads this, so the adopter's store
- * stays get/put/delete with no `list`. Persisted under a reserved key with a fixed-size
- * backup ring for integrity.
- */
-interface ContentIndex {
-    /** Monotonic, bumped on every save; orders the backup ring during recovery. */
-    readonly version: number;
-    /** Every key that exists, sorted and de-duplicated (deterministic, CLAUDE §2). */
-    readonly keys: readonly string[];
-    /** Checksum over version + keys, so a corrupt stored index is caught on read. */
-    readonly checksum: string;
-}
-/** The empty index of a fresh store: version 0, no keys. */
-declare function emptyIndex(): ContentIndex;
-/**
- * Load the index, recovering through the backup ring if the live copy is missing or
- * corrupt (DESIGN §11d): the highest valid version among the ring slots wins. Returns
- * the empty index when nothing valid is found, a fresh store, or the accepted residual
- * case where the live index and every backup are lost (the files still exist by key,
- * but cannot be enumerated until something rewrites the index).
- */
-declare function loadIndex(store: BlobStore): Promise<ContentIndex>;
-/**
- * Write a new index whose keys are `nextKeys`, backing up the one it replaces first
- * (DESIGN §11d). The previous index goes into its ring slot (`version % ring`, oldest
- * overwritten), then the new index is written to the live key, a constant two writes
- * per save regardless of ring size. Returns the new index (the caller's next `prev`).
- */
-declare function saveIndex(store: BlobStore, prev: ContentIndex, nextKeys: readonly string[]): Promise<ContentIndex>;
-
 /**
  * The authors byline (DESIGN §6.11). An `authors` field stores an ordered list of
  * author refs; the compiler renders them as one grammatical line. Everything here
@@ -1235,4 +1267,4 @@ declare function escapeJsonStringContent(value: string): string;
  */
 declare function sanitizeUrl(url: string): string;
 
-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 Diagnostic, 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 IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type PageEntry, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PurgeService, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type Scope, type Severity, type SiteConfig, type SortFile, type TemplateAnalysis, type TokenContext, type TokenRef, type TreeNode, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, contentHash, contentTypeFor, deriveFields, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isFieldType, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, processImage, publishSite, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, wholeValueToken };
+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 Diagnostic, 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 IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type PageEntry, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type Scope, type Severity, type SiteConfig, type SortFile, type TemplateAnalysis, type TokenContext, type TokenRef, type TreeNode, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, contentHash, contentTypeFor, deriveFields, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isFieldType, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, wholeValueToken };

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   InMemoryBlobStore,
   InMemoryContentSource,
   IndexedStore,
+  RESERVED_PREFIX,
   analyzeTemplate,
   buildAuthoringReference,
   buildContentIndex,
@@ -48,6 +49,7 @@ import {
   parseSortFile,
   processImage,
   publishSite,
+  reconcileIndex,
   renderAuthors,
   renderReferenceMarkdown,
   sanitizeUrl,
@@ -59,7 +61,7 @@ import {
   validateSite,
   valueKindOf,
   wholeValueToken
-} from "./chunk-G2UEZTYC.js";
+} from "./chunk-22WHPW5E.js";
 export {
   ContentParseError,
   DEFAULT_DIRS,
@@ -69,6 +71,7 @@ export {
   InMemoryBlobStore,
   InMemoryContentSource,
   IndexedStore,
+  RESERVED_PREFIX,
   analyzeTemplate,
   buildAuthoringReference,
   buildContentIndex,
@@ -110,6 +113,7 @@ export {
   parseSortFile,
   processImage,
   publishSite,
+  reconcileIndex,
   renderAuthors,
   renderReferenceMarkdown,
   sanitizeUrl,