@gmickel/gno 1.30.7 → 1.32.0

package/src/sdk/client.ts

@@ -34,10 +34,12 @@ import type {
   GnoIndexResult,
   GnoIndexStatus,
   GnoListOptions,
+  GnoMoveNoteApplyOptions,
   GnoMoveNoteOptions,
   GnoMultiGetOptions,
   GnoQueryOptions,
   GnoRefactorNoteResult,
+  GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
   GnoUpdateOptions,
@@ -47,6 +49,10 @@ import type {
   KnowledgeImpactInput,
   KnowledgeImpactResult,
   ListKnowledgeChangesInput,
+  SectionTargetCreateResult,
+  SectionTargetCreateSelector,
+  SectionTargetResolveResult,
+  SectionTargetV1,
 } from "./types";
 
 import {
@@ -82,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 {
@@ -122,7 +131,17 @@ import {
   RETRIEVAL_TRACE_METADATA,
   type RetrievalTraceSession,
 } from "../core/retrieval-trace-session";
-import { extractSections } from "../core/sections";
+import {
+  CANONICAL_URI_EXCEEDS_TRANSPORT_BOUNDS,
+  createSectionTarget as createSectionTargetCore,
+  extractSections,
+  isTransportBoundedCanonicalUri,
+  parseSectionTargetCreateSelector,
+  parseSectionTargetV1,
+  projectSectionTargetCreateResult,
+  projectSectionTargetResolveResult,
+  resolveSectionTarget as resolveSectionTargetCore,
+} from "../core/sections";
 import { normalizeStructuredQueryInput } from "../core/structured-query";
 import { parseAndValidateTagFilter } from "../core/tags";
 import {
@@ -320,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;
@@ -1643,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(
@@ -1835,6 +1901,62 @@ class GnoClientImpl implements GnoClient {
     return extractSections(document.content);
   }
 
+  async createSectionTarget(
+    ref: string,
+    selector: SectionTargetCreateSelector
+  ): Promise<SectionTargetCreateResult> {
+    this.assertOpen();
+    const parsed = parseSectionTargetCreateSelector(selector);
+    if (!parsed.ok) {
+      throw sdkError("VALIDATION", parsed.error);
+    }
+    const document = await getDocumentByRef(this.store, this.config, ref, {});
+    // Top-level response uri shares schema maxLength — reject before create.
+    if (!isTransportBoundedCanonicalUri(document.uri)) {
+      throw sdkError("VALIDATION", CANONICAL_URI_EXCEEDS_TRANSPORT_BOUNDS);
+    }
+    // Canonical identity from stored document — never from caller.
+    const target = await createSectionTargetCore({
+      content: document.content,
+      uri: document.uri,
+      ...parsed.value,
+    });
+    if (!target) {
+      const sections = extractSections(document.content);
+      const matched =
+        parsed.value.anchor !== undefined
+          ? sections.some((section) => section.anchor === parsed.value.anchor)
+          : sections.some((section) => section.line === parsed.value.line);
+      if (!matched) {
+        throw sdkError("NOT_FOUND", "Section not found");
+      }
+      throw sdkError("VALIDATION", "Section target exceeds size bounds");
+    }
+    return projectSectionTargetCreateResult(document.uri, target);
+  }
+
+  async resolveSectionTarget(
+    ref: string,
+    target: SectionTargetV1
+  ): Promise<SectionTargetResolveResult> {
+    this.assertOpen();
+    const parsed = parseSectionTargetV1(target);
+    if (!parsed.ok) {
+      throw sdkError("VALIDATION", parsed.error);
+    }
+    const document = await getDocumentByRef(this.store, this.config, ref, {});
+    // Top-level uri must fit schema — citation fail-closed does not repair it.
+    if (!isTransportBoundedCanonicalUri(document.uri)) {
+      throw sdkError("VALIDATION", CANONICAL_URI_EXCEEDS_TRANSPORT_BOUNDS);
+    }
+    const resolution = await resolveSectionTargetCore({
+      content: document.content,
+      target: parsed.value,
+      uri: document.uri,
+    });
+    return projectSectionTargetResolveResult(document.uri, resolution);
+  }
+
   async close(): Promise<void> {
     if (this.closed) {
       return;

package/src/sdk/index.ts

@@ -28,6 +28,7 @@ export type { IndexStatus } from "../store/types";
 export { GnoSdkError, sdkError } from "./errors";
 export { createGnoClient } from "./client";
 export type {
+  DocumentSection,
   GnoAskOptions,
   GnoCaptureOptions,
   GnoCaptureResult,
@@ -39,6 +40,9 @@ export type {
   GnoClientInitOptions,
   GnoEmbedOptions,
   GnoEmbedResult,
+  GnoFileRefactorApplyConfirmation,
+  GnoFileRefactorApplyResult,
+  GnoFileRefactorPreviewPlan,
   GnoGetOptions,
   GnoGetResult,
   GnoIndexOptions,
@@ -48,10 +52,14 @@ export type {
   GnoListOptions,
   GnoListResult,
   GnoModelOverrides,
+  GnoMoveNoteApplyOptions,
+  GnoMoveNoteOptions,
   GnoMultiGetDocument,
   GnoMultiGetOptions,
   GnoMultiGetResult,
   GnoQueryOptions,
+  GnoRenameNoteApplyOptions,
+  GnoRenameNoteOptions,
   GnoProjectHintOptions,
   GnoSearchOptions,
   GnoSkippedDocument,
@@ -64,6 +72,10 @@ export type {
   KnowledgeImpactInput,
   KnowledgeImpactResult,
   ListKnowledgeChangesInput,
+  SectionTargetCreateResult,
+  SectionTargetCreateSelector,
+  SectionTargetResolveResult,
+  SectionTargetV1,
 } from "./types";
 export {
   ContextCapsuleContractError,

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,
@@ -52,7 +56,13 @@ import type {
   RetrievalTraceListResult,
   RetrievalTracePurgeResult as RetrievalTraceManagementPurgeResult,
 } from "../core/retrieval-trace-management";
-import type { DocumentSection } from "../core/sections";
+import type {
+  DocumentSection,
+  SectionTargetCreateResult,
+  SectionTargetCreateSelector,
+  SectionTargetResolveResult,
+  SectionTargetV1,
+} from "../core/sections";
 import type { SyncResult } from "../ingestion";
 import type { DownloadPolicy } from "../llm/policy";
 import type {
@@ -67,10 +77,15 @@ import type { IndexStatus } from "../store/types";
 export type {
   AskResult,
   Config,
+  DocumentSection,
   DownloadPolicy,
   IndexStatus,
   SearchOptions,
   SearchResults,
+  SectionTargetCreateResult,
+  SectionTargetCreateSelector,
+  SectionTargetResolveResult,
+  SectionTargetV1,
   SyncResult,
 };
 export type { AskOptions, HybridSearchOptions } from "../pipeline/types";
@@ -251,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;
@@ -339,11 +370,38 @@ 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>;
   getSections(ref: string): Promise<DocumentSection[]>;
+  /**
+   * Create a durable SectionTargetV1 for a heading in a stored document.
+   * Provide exactly one of `anchor` or `line`. Canonical URI comes from the
+   * resolved stored document, never from the caller.
+   */
+  createSectionTarget(
+    ref: string,
+    selector: SectionTargetCreateSelector
+  ): Promise<SectionTargetCreateResult>;
+  /**
+   * Conservatively resolve a SectionTargetV1 against a stored document.
+   * Navigable results include citation evidence; ambiguous/stale/missing do not.
+   */
+  resolveSectionTarget(
+    ref: string,
+    target: SectionTargetV1
+  ): Promise<SectionTargetResolveResult>;
   close(): Promise<void>;
 }