@gmickel/gno 1.31.0 → 1.33.0

package/src/publish/obsidian-sanitize.ts

@@ -2,12 +2,23 @@
  * Obsidian-aware markdown pre-processor for publish export.
  *
  * Strips wikilinks, drops navigation sidebar idioms, removes references to
- * private (`_internal/`) paths, and warns on unresolvable image embeds before
- * the markdown enters the publish artifact.
+ * private (`_internal/`) paths, and resolves/bundles local raster embeds when
+ * an attachment context is provided (otherwise drops image embeds with a
+ * warning for backward compatibility).
  *
  * @module src/publish/obsidian-sanitize
  */
 
+import { discoverImageOccurrences } from "./attachment-discover";
+import { safePercentDecode } from "./attachment-path";
+import {
+  rewriteAttachmentsInMarkdown,
+  type AttachmentDiagnostic,
+  type AttachmentResolveContext,
+  type AttachmentRewriteResult,
+  type PendingAssetPayload,
+} from "./attachment-resolver";
+
 const WIKILINK_INTERNAL_PREFIX = /_internal\//i;
 const NAV_SIDEBAR_LINE = /^(!?\[\[[^\]]+\]\]\s*\|?\s*)+$/;
 const IMAGE_EMBED = /!\[\[([^\]]+)\]\]/g;
@@ -16,6 +27,7 @@ const ALIASED_WIKILINK = /\[\[([^\]|]+)\|([^\]]+)\]\]/g;
 const BARE_WIKILINK = /\[\[([^\]]+)\]\]/g;
 const TAIL_SEGMENT = /[^/]+$/;
 const BLOCK_ID_SUFFIX = /#\^?[\w-]+$/;
+const EXTERNAL_DESTINATION = /^(?:\/\/|[a-z][a-z0-9+.-]*:)/iu;
 
 export interface SanitizeWarning {
   kind:
@@ -31,6 +43,13 @@ export interface SanitizeResult {
   warnings: SanitizeWarning[];
 }
 
+export interface PublishSanitizeResult extends SanitizeResult {
+  diagnostics: AttachmentDiagnostic[];
+  externalCount: number;
+  payloads: Map<string, PendingAssetPayload>;
+  preDedupRawBytes: number;
+}
+
 const splitFrontmatter = (
   source: string
 ): { body: string; frontmatter: string } => {
@@ -61,8 +80,57 @@ const deriveLinkDisplay = (target: string): string => {
   return tail.trim() || raw;
 };
 
-export function sanitizeObsidianMarkdown(source: string): SanitizeResult {
-  const { body, frontmatter } = splitFrontmatter(source);
+const isPrivateImageReference = (sourceRef: string): boolean => {
+  const trimmed = sourceRef.trim();
+  if (EXTERNAL_DESTINATION.test(trimmed)) {
+    return false;
+  }
+  const decoded = safePercentDecode(trimmed);
+  if (decoded === null) {
+    return false;
+  }
+  return (
+    decoded
+      .split(/[?#]/u, 1)[0]
+      ?.split("/")
+      .some((segment) => segment.toLowerCase() === "_internal") ?? false
+  );
+};
+
+/**
+ * Remove private image references before attachment resolution can read bytes
+ * or replace the authored path with an opaque gno-asset sentinel.
+ */
+const stripPrivateImageReferences = (
+  body: string
+): { markdown: string; warnings: SanitizeWarning[] } => {
+  const replacements = discoverImageOccurrences(body)
+    .filter((occurrence) => isPrivateImageReference(occurrence.sourceRef))
+    .map((occurrence) => ({
+      detail: occurrence.sourceRef.trim(),
+      end: occurrence.end,
+      start: occurrence.start,
+    }));
+  let markdown = body;
+  for (const replacement of [...replacements].sort(
+    (left, right) => right.start - left.start
+  )) {
+    markdown =
+      markdown.slice(0, replacement.start) + markdown.slice(replacement.end);
+  }
+  return {
+    markdown,
+    warnings: replacements.map((replacement) => ({
+      detail: replacement.detail,
+      kind: "internal-reference-stripped" as const,
+    })),
+  };
+};
+
+const applyWikilinkSanitize = (
+  body: string,
+  options: { dropImageEmbeds: boolean }
+): { markdown: string; warnings: SanitizeWarning[] } => {
   const warnings: SanitizeWarning[] = [];
   const lines = body.split("\n");
   const output: string[] = [];
@@ -81,13 +149,15 @@ export function sanitizeObsidianMarkdown(source: string): SanitizeResult {
 
     let line = rawLine;
 
-    line = line.replace(IMAGE_EMBED, (_match, target: string) => {
-      warnings.push({
-        kind: "image-embed-dropped",
-        detail: target.trim(),
+    if (options.dropImageEmbeds) {
+      line = line.replace(IMAGE_EMBED, (_match, target: string) => {
+        warnings.push({
+          kind: "image-embed-dropped",
+          detail: target.trim(),
+        });
+        return "";
       });
-      return "";
-    });
+    }
 
     line = line.replace(INTERNAL_WIKILINK, (match) => {
       warnings.push({
@@ -134,9 +204,46 @@ export function sanitizeObsidianMarkdown(source: string): SanitizeResult {
     output.push(line);
   }
 
+  return { markdown: output.join("\n"), warnings };
+};
+
+/**
+ * Legacy sync sanitizer: drops Obsidian image embeds and converts wikilinks.
+ * Prefer `sanitizePublishMarkdown` when attachment bundling is enabled.
+ */
+export function sanitizeObsidianMarkdown(source: string): SanitizeResult {
+  const { body, frontmatter } = splitFrontmatter(source);
+  const sanitized = applyWikilinkSanitize(body, { dropImageEmbeds: true });
+  return {
+    markdown: `${frontmatter}${sanitized.markdown}`,
+    warnings: sanitized.warnings,
+  };
+}
+
+/**
+ * Parser-aware publish sanitize: resolve/rewrite local rasters in the same
+ * pass as Obsidian cleanup (image discovery is not a second independent scan).
+ */
+export async function sanitizePublishMarkdown(
+  source: string,
+  attachmentCtx: AttachmentResolveContext
+): Promise<PublishSanitizeResult> {
+  const { body, frontmatter } = splitFrontmatter(source);
+  const privateImages = stripPrivateImageReferences(body);
+  const rewritten: AttachmentRewriteResult = await rewriteAttachmentsInMarkdown(
+    privateImages.markdown,
+    attachmentCtx
+  );
+  const sanitized = applyWikilinkSanitize(rewritten.markdown, {
+    dropImageEmbeds: false,
+  });
   return {
-    markdown: `${frontmatter}${output.join("\n")}`,
-    warnings,
+    diagnostics: rewritten.diagnostics,
+    externalCount: rewritten.externalCount,
+    markdown: `${frontmatter}${sanitized.markdown}`,
+    payloads: rewritten.payloads,
+    preDedupRawBytes: rewritten.preDedupRawBytes,
+    warnings: [...privateImages.warnings, ...sanitized.warnings],
   };
 }
 
@@ -159,7 +266,8 @@ export function formatSanitizeWarnings(warnings: SanitizeWarning[]): string[] {
   }
 
   const labels: Record<SanitizeWarning["kind"], string> = {
-    "image-embed-dropped": "Image embeds dropped (attachments not bundled yet)",
+    "image-embed-dropped":
+      "Image embeds dropped (unsupported, missing, or unresolved)",
     "internal-reference-stripped": "Private `_internal/` references stripped",
     "nav-sidebar-dropped": "Navigation sidebar lines dropped",
     "wikilink-unresolved":

package/src/sdk/client.ts

@@ -34,10 +34,12 @@ import type {
   GnoIndexResult,
   GnoIndexStatus,
   GnoListOptions,
+  GnoMoveNoteApplyOptions,
   GnoMoveNoteOptions,
   GnoMultiGetOptions,
   GnoQueryOptions,
   GnoRefactorNoteResult,
+  GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
   GnoUpdateOptions,
@@ -86,20 +88,23 @@ import { writeCapturePlanFile } from "../core/capture-write";
 import { projectCollectionEgressPolicy } from "../core/collection-egress-policy-projection";
 import { CollectionEgressPolicyService } from "../core/collection-egress-policy-service";
 import { applyConfigChange } from "../core/config-mutation";
+import { getDocumentCapabilities } from "../core/document-capabilities";
 import { EgressAuditService } from "../core/egress-audit";
 import { authorizeCurrentEgress } from "../core/egress-authorization";
+import { atomicWrite, copyFilePath, createFolderPath } from "../core/file-ops";
 import {
-  atomicWrite,
-  copyFilePath,
-  createFolderPath,
-  renameFilePath,
-} from "../core/file-ops";
-import {
+  applyCanonicalFileRefactor,
+  assertFileRefactorSyncConverged,
+  buildCanonicalRefactorPlan,
+  buildDurableFileRefactorApplyDeps,
   buildRefactorWarnings,
+  parseRefactorApplyConfirmation,
   planCreateFolder,
   planDuplicateRefactor,
-  planMoveRefactor,
-  planRenameRefactor,
+  resolveMoveTarget,
+  resolveRenameTarget,
+  type FileRefactorApplyResult,
+  type FileRefactorPreviewPlan,
 } from "../core/file-refactors";
 import { resolveEffectiveIndex } from "../core/indexed-reference";
 import {
@@ -334,6 +339,52 @@ class GnoClientImpl implements GnoClient {
     return filtered;
   }
 
+  private requireRefactorApplyConfirmation(options: {
+    schemaVersion?: unknown;
+    planDigest?: unknown;
+    confirmation?: unknown;
+  }) {
+    const parsed = parseRefactorApplyConfirmation(options);
+    if ("error" in parsed) {
+      throw sdkError("VALIDATION", parsed.message);
+    }
+    return parsed;
+  }
+
+  private async prepareRefactorSource(ref: string) {
+    const doc = await getDocumentByRef(this.store, this.config, ref, {});
+    const stored = await this.store.getDocumentByUri(doc.uri);
+    if (!stored.ok || !stored.value) {
+      throw sdkError("NOT_FOUND", "Document not found");
+    }
+    const storedDoc = stored.value;
+    const collection = this.getCollections(storedDoc.collection)[0];
+    if (!collection) {
+      throw sdkError(
+        "VALIDATION",
+        `Collection not found: ${storedDoc.collection}`
+      );
+    }
+    const capabilities = getDocumentCapabilities({
+      sourceExt: storedDoc.sourceExt,
+      sourceMime: storedDoc.sourceMime,
+      contentAvailable: storedDoc.mirrorHash !== null,
+      recordKey: storedDoc.recordKey,
+    });
+    if (!capabilities.editable) {
+      throw sdkError(
+        "VALIDATION",
+        capabilities.reason ?? "Document is read-only in place."
+      );
+    }
+    return {
+      storedDoc,
+      collection,
+      sourceFullPath: `${collection.path}/${storedDoc.relPath}`,
+      editable: capabilities.editable,
+    };
+  }
+
   private async createRuntimePorts(options: {
     embed?: boolean;
     expand?: boolean;
@@ -1657,125 +1708,126 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
-  async renameNote(
+  async previewRenameNote(
     options: GnoRenameNoteOptions
-  ): Promise<GnoRefactorNoteResult> {
+  ): Promise<FileRefactorPreviewPlan> {
     this.assertOpen();
-    const doc = await getDocumentByRef(
-      this.store,
-      this.config,
-      options.ref,
-      {}
-    );
-    const stored = await this.store.getDocumentByUri(doc.uri);
-    if (!stored.ok || !stored.value) {
-      throw sdkError("NOT_FOUND", "Document not found");
-    }
-    const storedDoc = stored.value;
-    const collection = this.getCollections(storedDoc.collection)[0];
-    if (!collection) {
-      throw sdkError(
-        "VALIDATION",
-        `Collection not found: ${storedDoc.collection}`
-      );
-    }
-    const plan = planRenameRefactor({
-      collection: collection.name,
-      currentRelPath: storedDoc.relPath,
+    const prepared = await this.prepareRefactorSource(options.ref);
+    const target = resolveRenameTarget({
+      collection: prepared.collection.name,
+      currentRelPath: prepared.storedDoc.relPath,
       nextName: options.name,
     });
-    const currentPath = `${collection.path}/${storedDoc.relPath}`;
-    const nextPath = `${collection.path}/${plan.nextRelPath}`;
-    await renameFilePath(currentPath, nextPath);
-    await defaultSyncService.syncCollection(
-      collection,
-      this.store,
-      withContentTypeRules({ runUpdateCmd: false }, this.config)
-    );
-    const linksResult = await this.store.getLinksForDoc(storedDoc.id);
-    const backlinksResult = await this.store.getBacklinksForDoc(storedDoc.id);
-    if (!linksResult.ok || !backlinksResult.ok) {
-      throw sdkError("STORE", "Failed to compute refactor warnings");
-    }
-    return {
-      uri: plan.nextUri,
-      path: nextPath,
-      relPath: plan.nextRelPath,
-      warnings: buildRefactorWarnings(
-        {
-          backlinks: backlinksResult.value.length,
-          wikiLinks: linksResult.value.filter(
-            (entry) => entry.linkType === "wiki"
-          ).length,
-          markdownLinks: linksResult.value.filter(
-            (entry) => entry.linkType === "markdown"
-          ).length,
+    return buildCanonicalRefactorPlan({
+      operation: "rename",
+      doc: prepared.storedDoc,
+      collection: prepared.collection,
+      sourceFullPath: prepared.sourceFullPath,
+      target,
+      store: this.store,
+      sourceEditable: prepared.editable,
+    });
+  }
+
+  async previewMoveNote(
+    options: GnoMoveNoteOptions
+  ): Promise<FileRefactorPreviewPlan> {
+    this.assertOpen();
+    const prepared = await this.prepareRefactorSource(options.ref);
+    const target = resolveMoveTarget({
+      collection: prepared.collection.name,
+      currentRelPath: prepared.storedDoc.relPath,
+      folderPath: options.folderPath,
+      nextName: options.name,
+    });
+    return buildCanonicalRefactorPlan({
+      operation: "move",
+      doc: prepared.storedDoc,
+      collection: prepared.collection,
+      sourceFullPath: prepared.sourceFullPath,
+      target,
+      store: this.store,
+      sourceEditable: prepared.editable,
+    });
+  }
+
+  async renameNote(
+    options: GnoRenameNoteApplyOptions
+  ): Promise<FileRefactorApplyResult> {
+    this.assertOpen();
+    const confirmation = this.requireRefactorApplyConfirmation(options);
+    const prepared = await this.prepareRefactorSource(options.ref);
+    const target = resolveRenameTarget({
+      collection: prepared.collection.name,
+      currentRelPath: prepared.storedDoc.relPath,
+      nextName: options.name,
+    });
+    const plan = await buildCanonicalRefactorPlan({
+      operation: "rename",
+      doc: prepared.storedDoc,
+      collection: prepared.collection,
+      sourceFullPath: prepared.sourceFullPath,
+      target,
+      store: this.store,
+      sourceEditable: prepared.editable,
+    });
+    const apply = await applyCanonicalFileRefactor({
+      plan,
+      confirmation,
+      deps: buildDurableFileRefactorApplyDeps({
+        collection: prepared.collection,
+        store: this.store,
+        syncAfterCommit: async () => {
+          const syncResult = await defaultSyncService.syncCollection(
+            prepared.collection,
+            this.store,
+            withContentTypeRules({ runUpdateCmd: false }, this.config)
+          );
+          assertFileRefactorSyncConverged(syncResult);
         },
-        { filenameChanged: true }
-      ).warnings,
-    };
+      }),
+    });
+    return apply;
   }
 
-  async moveNote(options: GnoMoveNoteOptions): Promise<GnoRefactorNoteResult> {
+  async moveNote(
+    options: GnoMoveNoteApplyOptions
+  ): Promise<FileRefactorApplyResult> {
     this.assertOpen();
-    const doc = await getDocumentByRef(
-      this.store,
-      this.config,
-      options.ref,
-      {}
-    );
-    const stored = await this.store.getDocumentByUri(doc.uri);
-    if (!stored.ok || !stored.value) {
-      throw sdkError("NOT_FOUND", "Document not found");
-    }
-    const storedDoc = stored.value;
-    const collection = this.getCollections(storedDoc.collection)[0];
-    if (!collection) {
-      throw sdkError(
-        "VALIDATION",
-        `Collection not found: ${storedDoc.collection}`
-      );
-    }
-    const plan = planMoveRefactor({
-      collection: collection.name,
-      currentRelPath: storedDoc.relPath,
+    const confirmation = this.requireRefactorApplyConfirmation(options);
+    const prepared = await this.prepareRefactorSource(options.ref);
+    const target = resolveMoveTarget({
+      collection: prepared.collection.name,
+      currentRelPath: prepared.storedDoc.relPath,
       folderPath: options.folderPath,
       nextName: options.name,
     });
-    const currentPath = `${collection.path}/${storedDoc.relPath}`;
-    const nextPath = `${collection.path}/${plan.nextRelPath}`;
-    await mkdir(dirname(nextPath), { recursive: true });
-    await renameFilePath(currentPath, nextPath);
-    await defaultSyncService.syncCollection(
-      collection,
-      this.store,
-      withContentTypeRules({ runUpdateCmd: false }, this.config)
-    );
-    const linksResult = await this.store.getLinksForDoc(storedDoc.id);
-    const backlinksResult = await this.store.getBacklinksForDoc(storedDoc.id);
-    if (!linksResult.ok || !backlinksResult.ok) {
-      throw sdkError("STORE", "Failed to compute refactor warnings");
-    }
-    return {
-      uri: plan.nextUri,
-      path: nextPath,
-      relPath: plan.nextRelPath,
-      warnings: buildRefactorWarnings(
-        {
-          backlinks: backlinksResult.value.length,
-          wikiLinks: linksResult.value.filter(
-            (entry) => entry.linkType === "wiki"
-          ).length,
-          markdownLinks: linksResult.value.filter(
-            (entry) => entry.linkType === "markdown"
-          ).length,
+    const plan = await buildCanonicalRefactorPlan({
+      operation: "move",
+      doc: prepared.storedDoc,
+      collection: prepared.collection,
+      sourceFullPath: prepared.sourceFullPath,
+      target,
+      store: this.store,
+      sourceEditable: prepared.editable,
+    });
+    const apply = await applyCanonicalFileRefactor({
+      plan,
+      confirmation,
+      deps: buildDurableFileRefactorApplyDeps({
+        collection: prepared.collection,
+        store: this.store,
+        syncAfterCommit: async () => {
+          const syncResult = await defaultSyncService.syncCollection(
+            prepared.collection,
+            this.store,
+            withContentTypeRules({ runUpdateCmd: false }, this.config)
+          );
+          assertFileRefactorSyncConverged(syncResult);
         },
-        {
-          folderChanged: true,
-          filenameChanged: Boolean(options.name),
-        }
-      ).warnings,
-    };
+      }),
+    });
+    return apply;
   }
 
   async duplicateNote(

package/src/sdk/index.ts

@@ -40,6 +40,9 @@ export type {
   GnoClientInitOptions,
   GnoEmbedOptions,
   GnoEmbedResult,
+  GnoFileRefactorApplyConfirmation,
+  GnoFileRefactorApplyResult,
+  GnoFileRefactorPreviewPlan,
   GnoGetOptions,
   GnoGetResult,
   GnoIndexOptions,
@@ -49,10 +52,14 @@ export type {
   GnoListOptions,
   GnoListResult,
   GnoModelOverrides,
+  GnoMoveNoteApplyOptions,
+  GnoMoveNoteOptions,
   GnoMultiGetDocument,
   GnoMultiGetOptions,
   GnoMultiGetResult,
   GnoQueryOptions,
+  GnoRenameNoteApplyOptions,
+  GnoRenameNoteOptions,
   GnoProjectHintOptions,
   GnoSearchOptions,
   GnoSkippedDocument,

package/src/sdk/types.ts

@@ -32,6 +32,10 @@ import type {
   EgressAuditShowResult,
   EgressAuditStatusResult,
 } from "../core/egress-audit";
+import type {
+  FileRefactorApplyResult,
+  FileRefactorPreviewPlan,
+} from "../core/file-refactor-contract";
 import type {
   KnowledgeChangesResult,
   KnowledgeDiffResult,
@@ -262,6 +266,22 @@ export interface GnoMoveNoteOptions {
   name?: string;
 }
 
+/** Canonical apply confirmation — preview first, then pass exact digest. */
+export interface GnoFileRefactorApplyConfirmation {
+  schemaVersion: "1.0";
+  planDigest: string;
+  confirmation: "apply";
+}
+
+export interface GnoRenameNoteApplyOptions
+  extends GnoRenameNoteOptions, GnoFileRefactorApplyConfirmation {}
+
+export interface GnoMoveNoteApplyOptions
+  extends GnoMoveNoteOptions, GnoFileRefactorApplyConfirmation {}
+
+export type GnoFileRefactorPreviewPlan = FileRefactorPreviewPlan;
+export type GnoFileRefactorApplyResult = FileRefactorApplyResult;
+
 export interface GnoDuplicateNoteOptions {
   ref: string;
   folderPath?: string;
@@ -350,8 +370,18 @@ export interface GnoClient {
   capture(options: GnoCaptureOptions): Promise<GnoCaptureResult>;
   createNote(options: GnoCreateNoteOptions): Promise<GnoCreateNoteResult>;
   createFolder(options: GnoCreateFolderOptions): Promise<GnoCreateFolderResult>;
-  renameNote(options: GnoRenameNoteOptions): Promise<GnoRefactorNoteResult>;
-  moveNote(options: GnoMoveNoteOptions): Promise<GnoRefactorNoteResult>;
+  previewRenameNote(
+    options: GnoRenameNoteOptions
+  ): Promise<GnoFileRefactorPreviewPlan>;
+  previewMoveNote(
+    options: GnoMoveNoteOptions
+  ): Promise<GnoFileRefactorPreviewPlan>;
+  renameNote(
+    options: GnoRenameNoteApplyOptions
+  ): Promise<GnoFileRefactorApplyResult>;
+  moveNote(
+    options: GnoMoveNoteApplyOptions
+  ): Promise<GnoFileRefactorApplyResult>;
   duplicateNote(
     options: GnoDuplicateNoteOptions
   ): Promise<GnoRefactorNoteResult>;