@gmickel/gno 0.41.1 → 0.42.0

package/src/publish/export-service.ts

@@ -0,0 +1,238 @@
+/**
+ * Core publish export service used by CLI and local web UI.
+ *
+ * @module src/publish/export-service
+ */
+
+import type { Collection } from "../config/types";
+import type { DocumentRow, StorePort, TagRow } from "../store/types";
+
+import { parseRef } from "../cli/commands/ref-parser";
+import { parseFrontmatter } from "../ingestion/frontmatter";
+import {
+  buildPublishArtifact,
+  buildExportedMetadata,
+  derivePublishSlug,
+  deriveExportedSlug,
+  deriveExportedSummary,
+  deriveExportedTitle,
+  isPublishVisibility,
+  type PublishArtifact,
+  type PublishArtifactNote,
+  type PublishVisibility,
+} from "./artifact";
+
+export interface PublishExportCoreOptions {
+  routeSlug?: string;
+  summary?: string;
+  title?: string;
+  visibility?: PublishVisibility;
+}
+
+function resolveVisibility(visibility?: string): PublishVisibility {
+  if (visibility === undefined) {
+    return "public";
+  }
+  if (!isPublishVisibility(visibility)) {
+    throw new Error(
+      `Invalid visibility: ${visibility}. Must be public, secret-link, invite-only, or encrypted.`
+    );
+  }
+  return visibility;
+}
+
+async function lookupDocument(
+  store: StorePort,
+  ref: string
+): Promise<DocumentRow | null> {
+  const parsed = parseRef(ref);
+  if ("error" in parsed) {
+    throw new Error(parsed.error);
+  }
+
+  switch (parsed.type) {
+    case "docid": {
+      const result = await store.getDocumentByDocid(parsed.value);
+      if (!result.ok) {
+        throw new Error(result.error.message);
+      }
+      return result.value;
+    }
+    case "uri": {
+      const result = await store.getDocumentByUri(parsed.value);
+      if (!result.ok) {
+        throw new Error(result.error.message);
+      }
+      return result.value;
+    }
+    case "collPath": {
+      if (!(parsed.collection && parsed.relPath)) {
+        return null;
+      }
+      const result = await store.getDocument(parsed.collection, parsed.relPath);
+      if (!result.ok) {
+        throw new Error(result.error.message);
+      }
+      return result.value;
+    }
+  }
+}
+
+async function loadDocumentMarkdown(
+  store: StorePort,
+  doc: DocumentRow
+): Promise<string> {
+  if (!doc.mirrorHash) {
+    throw new Error(`Document has no converted content: ${doc.uri}`);
+  }
+
+  const result = await store.getContent(doc.mirrorHash);
+  if (!result.ok || !result.value) {
+    throw new Error(`Unable to load content for ${doc.uri}`);
+  }
+
+  return result.value;
+}
+
+async function loadDocumentTags(
+  store: StorePort,
+  doc: DocumentRow
+): Promise<TagRow[]> {
+  const result = await store.getTagsForDoc(doc.id);
+  if (!result.ok) {
+    throw new Error(
+      `Unable to load tags for ${doc.uri}: ${result.error.message}`
+    );
+  }
+
+  return result.value;
+}
+
+function chooseHomeNoteSlug(notes: PublishArtifactNote[]) {
+  const preferred = notes.find((note) =>
+    ["home", "index", "readme"].includes(note.slug)
+  );
+  return preferred?.slug ?? notes[0]?.slug;
+}
+
+function resolveCollection(
+  collections: Collection[],
+  target: string
+): Collection | null {
+  return collections.find((collection) => collection.name === target) ?? null;
+}
+
+async function exportCollectionArtifact(
+  store: StorePort,
+  collections: Collection[],
+  target: string,
+  options: PublishExportCoreOptions
+) {
+  const collection = resolveCollection(collections, target);
+  if (!collection) {
+    return null;
+  }
+
+  const docsResult = await store.listDocuments(collection.name);
+  if (!docsResult.ok) {
+    throw new Error(docsResult.error.message);
+  }
+
+  const activeDocs = docsResult.value
+    .filter((doc) => doc.active)
+    .sort((left, right) => left.uri.localeCompare(right.uri));
+
+  if (activeDocs.length === 0) {
+    throw new Error(`Collection "${collection.name}" has no active documents`);
+  }
+
+  const notes: PublishArtifactNote[] = [];
+  for (const doc of activeDocs) {
+    const markdown = await loadDocumentMarkdown(store, doc);
+    const tags = await loadDocumentTags(store, doc);
+    const frontmatter = parseFrontmatter(markdown).metadata;
+    const title = deriveExportedTitle(doc);
+    notes.push({
+      markdown,
+      metadata: buildExportedMetadata(doc, frontmatter, tags),
+      slug: deriveExportedSlug(doc),
+      summary: deriveExportedSummary(markdown, frontmatter),
+      title,
+    });
+  }
+
+  const title = options.title ?? collection.name;
+  const summary =
+    options.summary ??
+    `Published snapshot of the ${collection.name} collection from local GNO.`;
+  const routeSlug = derivePublishSlug([
+    options.routeSlug ?? "",
+    collection.name,
+    target,
+  ]);
+
+  return buildPublishArtifact({
+    homeNoteSlug: chooseHomeNoteSlug(notes),
+    notes,
+    routeSlug,
+    source: collection.name,
+    sourceType: "collection",
+    summary,
+    title,
+    visibility: resolveVisibility(options.visibility),
+  });
+}
+
+async function exportDocumentArtifact(
+  store: StorePort,
+  target: string,
+  options: PublishExportCoreOptions
+) {
+  const doc = await lookupDocument(store, target);
+  if (!doc?.active) {
+    throw new Error(`Document not found: ${target}`);
+  }
+
+  const markdown = await loadDocumentMarkdown(store, doc);
+  const tags = await loadDocumentTags(store, doc);
+  const frontmatter = parseFrontmatter(markdown).metadata;
+  const title = options.title ?? deriveExportedTitle(doc);
+  const summary =
+    options.summary ?? deriveExportedSummary(markdown, frontmatter);
+  const slug = deriveExportedSlug(doc);
+
+  return buildPublishArtifact({
+    notes: [
+      {
+        markdown,
+        metadata: buildExportedMetadata(doc, frontmatter, tags),
+        slug,
+        summary,
+        title,
+      },
+    ],
+    routeSlug: derivePublishSlug([options.routeSlug ?? "", slug, target]),
+    source: doc.uri,
+    sourceType: "note",
+    summary,
+    title,
+    visibility: resolveVisibility(options.visibility),
+  });
+}
+
+export async function exportPublishArtifact(input: {
+  collections: Collection[];
+  options: PublishExportCoreOptions;
+  store: StorePort;
+  target: string;
+}): Promise<PublishArtifact> {
+  return (
+    (await exportCollectionArtifact(
+      input.store,
+      input.collections,
+      input.target,
+      input.options
+    )) ??
+    (await exportDocumentArtifact(input.store, input.target, input.options))
+  );
+}

package/src/serve/AGENTS.md

@@ -65,22 +65,23 @@ Answer generation uses shared module to stay in sync with CLI:
 
 ## API Endpoints
 
-| Endpoint             | Method | Description                                |
-| -------------------- | ------ | ------------------------------------------ |
-| `/api/health`        | GET    | Health check                               |
-| `/api/status`        | GET    | Index stats, onboarding, health, bootstrap |
-| `/api/capabilities`  | GET    | Available features                         |
-| `/api/collections`   | GET    | List collections                           |
-| `/api/docs`          | GET    | List documents                             |
-| `/api/doc`           | GET    | Get document content                       |
-| `/api/search`        | POST   | BM25 search                                |
-| `/api/query`         | POST   | Hybrid search                              |
-| `/api/ask`           | POST   | AI answer with citations                   |
-| `/api/presets`       | GET    | List model presets                         |
-| `/api/presets`       | POST   | Switch preset (hot-reload)                 |
-| `/api/models/status` | GET    | Download progress                          |
-| `/api/models/pull`   | POST   | Start model download                       |
-| `/api/tags`          | GET    | List tags (with counts)                    |
+| Endpoint              | Method | Description                                |
+| --------------------- | ------ | ------------------------------------------ |
+| `/api/health`         | GET    | Health check                               |
+| `/api/status`         | GET    | Index stats, onboarding, health, bootstrap |
+| `/api/capabilities`   | GET    | Available features                         |
+| `/api/collections`    | GET    | List collections                           |
+| `/api/publish/export` | POST   | Export gno.sh publish artifact JSON        |
+| `/api/docs`           | GET    | List documents                             |
+| `/api/doc`            | GET    | Get document content                       |
+| `/api/search`         | POST   | BM25 search                                |
+| `/api/query`          | POST   | Hybrid search                              |
+| `/api/ask`            | POST   | AI answer with citations                   |
+| `/api/presets`        | GET    | List model presets                         |
+| `/api/presets`        | POST   | Switch preset (hot-reload)                 |
+| `/api/models/status`  | GET    | Download progress                          |
+| `/api/models/pull`    | POST   | Start model download                       |
+| `/api/tags`           | GET    | List tags (with counts)                    |
 
 ## Frontend
 

package/src/serve/CLAUDE.md

@@ -67,22 +67,23 @@ Answer generation uses shared module to stay in sync with CLI:
 
 ## API Endpoints
 
-| Endpoint             | Method | Description                                |
-| -------------------- | ------ | ------------------------------------------ |
-| `/api/health`        | GET    | Health check                               |
-| `/api/status`        | GET    | Index stats, onboarding, health, bootstrap |
-| `/api/capabilities`  | GET    | Available features                         |
-| `/api/collections`   | GET    | List collections                           |
-| `/api/docs`          | GET    | List documents                             |
-| `/api/doc`           | GET    | Get document content                       |
-| `/api/search`        | POST   | BM25 search                                |
-| `/api/query`         | POST   | Hybrid search                              |
-| `/api/ask`           | POST   | AI answer with citations                   |
-| `/api/presets`       | GET    | List model presets                         |
-| `/api/presets`       | POST   | Switch preset (hot-reload)                 |
-| `/api/models/status` | GET    | Download progress                          |
-| `/api/models/pull`   | POST   | Start model download                       |
-| `/api/tags`          | GET    | List tags (with counts)                    |
+| Endpoint              | Method | Description                                |
+| --------------------- | ------ | ------------------------------------------ |
+| `/api/health`         | GET    | Health check                               |
+| `/api/status`         | GET    | Index stats, onboarding, health, bootstrap |
+| `/api/capabilities`   | GET    | Available features                         |
+| `/api/collections`    | GET    | List collections                           |
+| `/api/publish/export` | POST   | Export gno.sh publish artifact JSON        |
+| `/api/docs`           | GET    | List documents                             |
+| `/api/doc`            | GET    | Get document content                       |
+| `/api/search`         | POST   | BM25 search                                |
+| `/api/query`          | POST   | Hybrid search                              |
+| `/api/ask`            | POST   | AI answer with citations                   |
+| `/api/presets`        | GET    | List model presets                         |
+| `/api/presets`        | POST   | Switch preset (hot-reload)                 |
+| `/api/models/status`  | GET    | Download progress                          |
+| `/api/models/pull`    | POST   | Start model download                       |
+| `/api/tags`           | GET    | List tags (with counts)                    |
 
 ## Frontend
 

package/src/serve/public/lib/publish-export.ts

@@ -0,0 +1,21 @@
+import type { PublishArtifact } from "../../../publish/artifact";
+
+export interface PublishExportResponse {
+  artifact: PublishArtifact;
+  fileName: string;
+  uploadUrl: string;
+}
+
+export function downloadPublishArtifactFile(
+  input: PublishExportResponse
+): void {
+  const blob = new Blob([JSON.stringify(input.artifact, null, 2)], {
+    type: "application/json",
+  });
+  const href = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = href;
+  anchor.download = input.fileName;
+  anchor.click();
+  URL.revokeObjectURL(href);
+}

package/src/serve/public/pages/Collections.tsx

@@ -23,6 +23,7 @@ import {
   Loader2Icon,
   MoreVerticalIcon,
   RefreshCwIcon,
+  Share2Icon,
 } from "lucide-react";
 import { useCallback, useEffect, useState } from "react";
 
@@ -66,6 +67,10 @@ import {
   TooltipTrigger,
 } from "../components/ui/tooltip";
 import { apiFetch } from "../hooks/use-api";
+import {
+  downloadPublishArtifactFile,
+  type PublishExportResponse,
+} from "../lib/publish-export";
 
 interface PageProps {
   navigate: (to: string | number) => void;
@@ -119,9 +124,11 @@ interface CollectionCardProps {
   collection: CollectionStats;
   onBrowse: () => void;
   onEmbeddingCleanup: () => void;
+  onExport: () => void;
   onModelSettings: () => void;
   onReindex: () => void;
   onRemove: () => void;
+  isExporting: boolean;
   isReindexing: boolean;
 }
 
@@ -149,9 +156,11 @@ function CollectionCard({
   collection,
   onBrowse,
   onEmbeddingCleanup,
+  onExport,
   onModelSettings,
   onReindex,
   onRemove,
+  isExporting,
   isReindexing,
 }: CollectionCardProps) {
   const embedPercent =
@@ -216,6 +225,20 @@ function CollectionCard({
                 <DatabaseIcon className="mr-2 size-4" />
                 Embedding cleanup
               </DropdownMenuItem>
+              <DropdownMenuItem
+                disabled={actionsDisabled || isExporting}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onExport();
+                }}
+              >
+                {isExporting ? (
+                  <Loader2Icon className="mr-2 size-4 animate-spin" />
+                ) : (
+                  <Share2Icon className="mr-2 size-4" />
+                )}
+                Export for gno.sh
+              </DropdownMenuItem>
               <DropdownMenuSeparator />
               <DropdownMenuItem
                 disabled={actionsDisabled || isReindexing}
@@ -337,6 +360,10 @@ export default function Collections({ navigate }: PageProps) {
   const [syncJobId, setSyncJobId] = useState<string | null>(null);
   const [syncTarget, setSyncTarget] = useState<SyncTarget>(null);
   const [syncError, setSyncError] = useState<string | null>(null);
+  const [exportError, setExportError] = useState<string | null>(null);
+  const [exportingCollectionName, setExportingCollectionName] = useState<
+    string | null
+  >(null);
   const [removeDialog, setRemoveDialog] = useState<CollectionStats | null>(
     null
   );
@@ -470,6 +497,30 @@ export default function Collections({ navigate }: PageProps) {
     await loadCollections();
   };
 
+  const handleExport = async (name: string) => {
+    setExportError(null);
+    setExportingCollectionName(name);
+
+    const { data, error: err } = await apiFetch<PublishExportResponse>(
+      "/api/publish/export",
+      {
+        body: JSON.stringify({ target: name }),
+        method: "POST",
+      }
+    );
+
+    setExportingCollectionName(null);
+
+    if (err) {
+      setExportError(err);
+      return;
+    }
+
+    if (data) {
+      downloadPublishArtifactFile(data);
+    }
+  };
+
   // Loading state
   if (loading) {
     return (
@@ -590,6 +641,14 @@ export default function Collections({ navigate }: PageProps) {
           </Card>
         )}
 
+        {exportError && (
+          <Card className="mx-auto mb-6 max-w-3xl border-destructive bg-destructive/10">
+            <CardContent className="py-4">
+              <p className="text-destructive text-sm">{exportError}</p>
+            </CardContent>
+          </Card>
+        )}
+
         {/* Error */}
         {error && (
           <Card className="mx-auto mb-6 max-w-md border-destructive bg-destructive/10">
@@ -626,6 +685,7 @@ export default function Collections({ navigate }: PageProps) {
               <CollectionCard
                 actionsDisabled={Boolean(syncJobId)}
                 collection={collection}
+                isExporting={exportingCollectionName === collection.name}
                 isReindexing={
                   Boolean(syncJobId) &&
                   syncTarget?.kind === "collection" &&
@@ -641,6 +701,9 @@ export default function Collections({ navigate }: PageProps) {
                   setEmbeddingCleanupDialog(collection);
                   setEmbeddingCleanupNote(null);
                 }}
+                onExport={() => {
+                  void handleExport(collection.name);
+                }}
                 onModelSettings={() => setModelDialogCollection(collection)}
                 onReindex={() => void handleReindex(collection.name)}
                 onRemove={() => setRemoveDialog(collection)}

package/src/serve/public/pages/DocView.tsx

@@ -13,6 +13,7 @@ import {
   LinkIcon,
   Loader2Icon,
   PencilIcon,
+  Share2Icon,
   SquareArrowOutUpRightIcon,
   TextIcon,
   TrashIcon,
@@ -63,6 +64,10 @@ import {
   parseDocumentDeepLink,
 } from "../lib/deep-links";
 import { waitForDocumentAvailability } from "../lib/document-availability";
+import {
+  downloadPublishArtifactFile,
+  type PublishExportResponse,
+} from "../lib/publish-export";
 import { subscribeWorkspaceActionRequest } from "../lib/workspace-events";
 
 interface PageProps {
@@ -287,6 +292,11 @@ export default function DocView({ navigate }: PageProps) {
   const [externalChangeNotice, setExternalChangeNotice] = useState<
     string | null
   >(null);
+  const [exportingPublishArtifact, setExportingPublishArtifact] =
+    useState(false);
+  const [publishExportError, setPublishExportError] = useState<string | null>(
+    null
+  );
 
   // Tag editing state
   const [editingTags, setEditingTags] = useState(false);
@@ -518,6 +528,32 @@ export default function DocView({ navigate }: PageProps) {
     }
   }, [doc, navigate]);
 
+  const handlePublishExport = useCallback(async () => {
+    if (!doc) {
+      return;
+    }
+
+    setPublishExportError(null);
+    setExportingPublishArtifact(true);
+    const { data, error: err } = await apiFetch<PublishExportResponse>(
+      "/api/publish/export",
+      {
+        body: JSON.stringify({ target: doc.uri }),
+        method: "POST",
+      }
+    );
+    setExportingPublishArtifact(false);
+
+    if (err) {
+      setPublishExportError(err);
+      return;
+    }
+
+    if (data) {
+      downloadPublishArtifactFile(data);
+    }
+  }, [doc]);
+
   const handleDelete = async () => {
     if (!doc) return;
 
@@ -1309,6 +1345,22 @@ export default function DocView({ navigate }: PageProps) {
                       <PencilIcon className="size-4" />
                       Edit
                     </Button>
+                    <Button
+                      className="gap-1.5"
+                      disabled={exportingPublishArtifact}
+                      onClick={() => {
+                        void handlePublishExport();
+                      }}
+                      size="sm"
+                      variant="outline"
+                    >
+                      {exportingPublishArtifact ? (
+                        <Loader2Icon className="size-4 animate-spin" />
+                      ) : (
+                        <Share2Icon className="size-4" />
+                      )}
+                      Export for gno.sh
+                    </Button>
                     <Button
                       className="gap-1.5"
                       onClick={handleStartRename}
@@ -1356,6 +1408,22 @@ export default function DocView({ navigate }: PageProps) {
                         Create editable copy
                       </Button>
                     )}
+                    <Button
+                      className="gap-1.5"
+                      disabled={exportingPublishArtifact}
+                      onClick={() => {
+                        void handlePublishExport();
+                      }}
+                      size="sm"
+                      variant="outline"
+                    >
+                      {exportingPublishArtifact ? (
+                        <Loader2Icon className="size-4 animate-spin" />
+                      ) : (
+                        <Share2Icon className="size-4" />
+                      )}
+                      Export for gno.sh
+                    </Button>
                     {doc.source.absPath && (
                       <>
                         <Button
@@ -1408,6 +1476,9 @@ export default function DocView({ navigate }: PageProps) {
             </>
           )}
         </div>
+        {publishExportError && (
+          <p className="pt-2 text-destructive text-sm">{publishExportError}</p>
+        )}
       </header>
 
       <div className="mx-auto flex max-w-[1800px] gap-5 px-6 xl:px-8">