@gmickel/gno 1.31.0 → 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,
@@ -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>;

package/src/serve/file-refactor-http.ts

@@ -0,0 +1,239 @@
+/**
+ * REST transport adapter for canonical reference-safe rename/move.
+ *
+ * Handlers must not implement link rewrite logic — they only build
+ * targets, call the core planner/apply service, and map typed results.
+ *
+ * @module src/serve/file-refactor-http
+ */
+
+import type {
+  FileRefactorApplyResult,
+  FileRefactorPreviewPlan,
+  FileRefactorReasonCode,
+} from "../core/file-refactors";
+
+import {
+  applyCanonicalFileRefactor,
+  buildCanonicalRefactorPlan,
+  buildDurableFileRefactorApplyDeps,
+  FILE_REFACTOR_APPLY_CONFIRMATION,
+  FILE_REFACTOR_SCHEMA_VERSION,
+  parseRefactorApplyConfirmation as parseCoreRefactorApplyConfirmation,
+  resolveMoveTarget,
+  resolveRenameTarget,
+} from "../core/file-refactors";
+
+export {
+  applyCanonicalFileRefactor,
+  buildCanonicalRefactorPlan,
+  buildDurableFileRefactorApplyDeps as buildFileRefactorApplyDeps,
+  resolveMoveTarget,
+  resolveRenameTarget,
+};
+
+export interface FileRefactorHttpError {
+  code: string;
+  message: string;
+  status: number;
+  details?: Record<string, unknown>;
+}
+
+export interface FileRefactorApplyHttpSuccess {
+  success: true;
+  uri: string;
+  path: string;
+  relPath: string;
+  planDigest: string;
+  status: FileRefactorApplyResult["status"];
+  apply: FileRefactorApplyResult;
+  refactorWarnings: {
+    warnings: string[];
+    backlinkCount: number;
+    wikiLinkCount: number;
+    markdownLinkCount: number;
+  };
+  warning?: string;
+}
+
+function warningsFromPlan(plan: FileRefactorPreviewPlan) {
+  return {
+    warnings: [...plan.safety.warnings],
+    backlinkCount: plan.safety.backlinkCount,
+    wikiLinkCount: plan.safety.wikiLinkCount,
+    markdownLinkCount: plan.safety.markdownLinkCount,
+  };
+}
+
+export function toRefactorPlanResponse(plan: FileRefactorPreviewPlan) {
+  return {
+    ...plan,
+    operation: plan.operation,
+    nextRelPath: plan.target.relPath,
+    nextUri: plan.target.uri,
+    refactorWarnings: warningsFromPlan(plan),
+  };
+}
+
+function reasonMessage(
+  status: FileRefactorApplyResult["status"],
+  reasonCode?: FileRefactorReasonCode
+): string {
+  switch (status) {
+    case "stale_plan":
+      return "This refactor plan is stale. Preview again, then confirm the exact plan digest.";
+    case "conflict":
+      return "Another workspace mutation is in progress or the target is unsafe. Retry after it finishes.";
+    case "unsupported":
+      if (
+        reasonCode === "capability_denied" ||
+        reasonCode === "read_only_document"
+      ) {
+        return "This document cannot be refactored in place from GNO.";
+      }
+      if (reasonCode === "occupied_target") {
+        return "A file with that name already exists at the destination";
+      }
+      return reasonCode
+        ? `Refactor cannot be applied (${reasonCode}).`
+        : "Refactor cannot be applied.";
+    case "failed_rolled_back":
+      if (reasonCode === "rollback_recovery_required") {
+        return "Refactor failed and needs recovery. Filesystem state may require manual inspection using the recovery journal id.";
+      }
+      return "Refactor failed and was rolled back. No partial file set was left behind.";
+    default:
+      return "Refactor failed.";
+  }
+}
+
+export function mapApplyResultToHttpError(
+  result: FileRefactorApplyResult
+): FileRefactorHttpError {
+  const reasonCode = "reasonCode" in result ? result.reasonCode : undefined;
+  const details: Record<string, unknown> = {
+    planDigest: result.planDigest,
+    status: result.status,
+    filesystem: result.filesystem,
+    indexConvergence: result.indexConvergence,
+  };
+  if (reasonCode) {
+    details.reasonCode = reasonCode;
+  }
+  if (result.filesystem.recoveryJournalId) {
+    details.recoveryJournalId = result.filesystem.recoveryJournalId;
+  }
+
+  if (result.status === "stale_plan") {
+    return {
+      code: "STALE_PLAN",
+      message: reasonMessage(result.status, reasonCode),
+      status: 409,
+      details,
+    };
+  }
+  if (result.status === "conflict") {
+    return {
+      code: "CONFLICT",
+      message: reasonMessage(result.status, reasonCode),
+      status: 409,
+      details,
+    };
+  }
+  if (result.status === "unsupported") {
+    if (
+      reasonCode === "capability_denied" ||
+      reasonCode === "read_only_document"
+    ) {
+      return {
+        code: "READ_ONLY",
+        message: reasonMessage(result.status, reasonCode),
+        status: 409,
+        details,
+      };
+    }
+    if (reasonCode === "occupied_target") {
+      return {
+        code: "CONFLICT",
+        message: reasonMessage(result.status, reasonCode),
+        status: 409,
+        details,
+      };
+    }
+    return {
+      code: "UNSUPPORTED",
+      message: reasonMessage(result.status, reasonCode),
+      status: 409,
+      details,
+    };
+  }
+  if (result.status === "failed_rolled_back") {
+    const recovery =
+      result.filesystem.state === "recovery_required" ||
+      reasonCode === "rollback_recovery_required";
+    return {
+      code: recovery ? "RECOVERY_REQUIRED" : "ROLLED_BACK",
+      message: reasonMessage(result.status, reasonCode),
+      status: 500,
+      details,
+    };
+  }
+
+  return {
+    code: "RUNTIME",
+    message: reasonMessage(result.status, reasonCode),
+    status: 500,
+    details,
+  };
+}
+
+export function mapApplyResultToHttpSuccess(input: {
+  plan: FileRefactorPreviewPlan;
+  result: FileRefactorApplyResult;
+  targetFullPath: string;
+  operationLabel: "renamed" | "moved";
+}): FileRefactorApplyHttpSuccess | FileRefactorHttpError {
+  const { plan, result, targetFullPath, operationLabel } = input;
+
+  if (
+    result.status !== "applied" &&
+    result.status !== "applied_with_sync_pending"
+  ) {
+    return mapApplyResultToHttpError(result);
+  }
+
+  const warning =
+    result.status === "applied_with_sync_pending"
+      ? `File ${operationLabel} on disk, but index refresh failed. Run Update All to reconcile the workspace.`
+      : undefined;
+
+  return {
+    success: true,
+    uri: plan.target.uri,
+    path: targetFullPath,
+    relPath: plan.target.relPath,
+    planDigest: result.planDigest,
+    status: result.status,
+    apply: result,
+    refactorWarnings: warningsFromPlan(plan),
+    warning,
+  };
+}
+
+export interface ParsedRefactorApplyConfirmation {
+  planDigest: string;
+  confirmation: typeof FILE_REFACTOR_APPLY_CONFIRMATION;
+  schemaVersion: typeof FILE_REFACTOR_SCHEMA_VERSION;
+}
+
+export function parseRefactorApplyConfirmation(body: {
+  planDigest?: unknown;
+  confirmation?: unknown;
+  schemaVersion?: unknown;
+}): ParsedRefactorApplyConfirmation | FileRefactorHttpError {
+  const parsed = parseCoreRefactorApplyConfirmation(body);
+  if ("error" in parsed) {
+    return { code: "VALIDATION", message: parsed.message, status: 400 };
+  }
+  return parsed;
+}