@gmickel/gno 1.31.0 → 1.32.0

package/spec/output-schemas/file-refactor-preview.schema.json

@@ -0,0 +1,393 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/file-refactor-preview@1.0",
+  "title": "GNO File Refactor Preview Plan",
+  "description": "Transport-neutral, versioned preview plan for reference-safe rename and same-collection move. Destination-only edit spans; filesystem atomicity is separate from post-commit index convergence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "operation",
+    "conflictPolicy",
+    "source",
+    "target",
+    "affectedDocuments",
+    "examinedReferences",
+    "preconditions",
+    "planDigest",
+    "safety",
+    "canApply",
+    "mutationBoundary"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "operation": {
+      "type": "string",
+      "enum": ["rename", "move"]
+    },
+    "conflictPolicy": {
+      "type": "string",
+      "enum": ["fail"]
+    },
+    "source": {
+      "$ref": "#/definitions/documentRef"
+    },
+    "target": {
+      "$ref": "#/definitions/documentRef"
+    },
+    "affectedDocuments": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": {
+        "$ref": "#/definitions/affectedDocument"
+      }
+    },
+    "examinedReferences": {
+      "type": "array",
+      "maxItems": 100000,
+      "items": {
+        "$ref": "#/definitions/examinedReference"
+      }
+    },
+    "preconditions": {
+      "$ref": "#/definitions/preconditions"
+    },
+    "planDigest": {
+      "$ref": "#/definitions/sha256"
+    },
+    "safety": {
+      "$ref": "#/definitions/safetySummary"
+    },
+    "canApply": {
+      "type": "boolean"
+    },
+    "mutationBoundary": {
+      "$ref": "#/definitions/mutationBoundary"
+    }
+  },
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "reasonCode": {
+      "type": "string",
+      "enum": [
+        "ambiguous_resolution",
+        "unsupported_syntax",
+        "malformed_syntax",
+        "stale_plan",
+        "capability_denied",
+        "occupied_target",
+        "sync_pending",
+        "cross_collection_unsupported",
+        "unsafe_target",
+        "external_destination",
+        "code_fence_context",
+        "inline_code_context",
+        "html_context",
+        "duplicate_basename_ambiguity",
+        "unicode_normalization_mismatch",
+        "destination_unchanged",
+        "read_only_document",
+        "relative_path_recalculated",
+        "reference_definition_site",
+        "filesystem_commit_failed",
+        "rollback_recovery_required"
+      ]
+    },
+    "documentRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uri", "relPath", "collection"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "relPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "collection": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
+    "destinationSpan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "coordinateSpace",
+        "startOffset",
+        "endOffset",
+        "originalDestination",
+        "replacementDestination"
+      ],
+      "properties": {
+        "coordinateSpace": {
+          "const": "utf16_code_units"
+        },
+        "startOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "endOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "originalDestination": {
+          "type": "string",
+          "maxLength": 4096
+        },
+        "replacementDestination": {
+          "type": "string",
+          "maxLength": 4096
+        }
+      }
+    },
+    "examinedReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["documentUri", "documentRelPath", "kind", "classification"],
+      "properties": {
+        "documentUri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "documentRelPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["wiki", "markdown", "markdown_definition", "opaque"]
+        },
+        "classification": {
+          "type": "string",
+          "enum": [
+            "rewriteable",
+            "unchanged",
+            "ambiguous",
+            "unsupported",
+            "malformed",
+            "invalid"
+          ]
+        },
+        "reasonCode": {
+          "$ref": "#/definitions/reasonCode"
+        },
+        "originalDestination": {
+          "type": "string",
+          "maxLength": 4096
+        },
+        "proposedDestination": {
+          "type": "string",
+          "maxLength": 4096
+        },
+        "edit": {
+          "$ref": "#/definitions/destinationSpan"
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "startCol": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "endCol": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "affectedDocument": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uri", "relPath", "contentFingerprint", "edits", "examined"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "relPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "contentFingerprint": {
+          "$ref": "#/definitions/sha256"
+        },
+        "edits": {
+          "type": "array",
+          "maxItems": 10000,
+          "items": {
+            "$ref": "#/definitions/destinationSpan"
+          }
+        },
+        "examined": {
+          "type": "array",
+          "maxItems": 100000,
+          "items": {
+            "$ref": "#/definitions/examinedReference"
+          }
+        }
+      }
+    },
+    "preconditions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sourceContentFingerprint",
+        "affectedContentFingerprints",
+        "targetPathFingerprint"
+      ],
+      "properties": {
+        "sourceContentFingerprint": {
+          "$ref": "#/definitions/sha256"
+        },
+        "affectedContentFingerprints": {
+          "type": "array",
+          "maxItems": 10000,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["uri", "fingerprint"],
+            "properties": {
+              "uri": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              },
+              "fingerprint": {
+                "$ref": "#/definitions/sha256"
+              }
+            }
+          }
+        },
+        "targetPathFingerprint": {
+          "$ref": "#/definitions/sha256"
+        }
+      }
+    },
+    "safetySummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rewriteableCount",
+        "unchangedCount",
+        "ambiguousCount",
+        "unsupportedCount",
+        "malformedCount",
+        "invalidCount",
+        "blockingReasonCodes",
+        "warnings",
+        "backlinkCount",
+        "wikiLinkCount",
+        "markdownLinkCount"
+      ],
+      "properties": {
+        "rewriteableCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "unchangedCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "ambiguousCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "unsupportedCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "malformedCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "invalidCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "blockingReasonCodes": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/definitions/reasonCode"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "type": "string",
+            "maxLength": 512
+          }
+        },
+        "backlinkCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "wikiLinkCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "markdownLinkCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "mutationBoundary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "filesystemCommit",
+        "indexConvergence",
+        "syncFailureDoesNotRollbackFilesystem"
+      ],
+      "properties": {
+        "filesystemCommit": {
+          "const": "atomic_all_or_rollback"
+        },
+        "indexConvergence": {
+          "const": "post_commit_separate"
+        },
+        "syncFailureDoesNotRollbackFilesystem": {
+          "const": true
+        }
+      }
+    }
+  }
+}

package/src/core/document-capabilities.ts

@@ -24,6 +24,19 @@ function isTextLikeMime(mime: string): boolean {
   return mime.startsWith("text/");
 }
 
+/**
+ * True when a document may carry markdown/wiki/HTML references in mirror text.
+ * Used by refactor inventory completeness to fail closed on missing mirrors.
+ * Non-text binaries (pdf/images/…) are omitted — they cannot hold those refs.
+ */
+export function isTextLikeReferenceDocument(
+  sourceExt: string,
+  sourceMime: string
+): boolean {
+  const ext = sourceExt.toLowerCase();
+  return EDITABLE_EXTENSIONS.has(ext) || isTextLikeMime(sourceMime);
+}
+
 export function getDocumentCapabilities(input: {
   sourceExt: string;
   sourceMime: string;

package/src/core/file-ops.ts

@@ -27,13 +27,25 @@ export async function atomicWrite(
   }
 }
 
+type AtomicCreateContent =
+  | string
+  | Blob
+  | ArrayBuffer
+  | Uint8Array
+  | ReturnType<typeof Bun.file>;
+
+/**
+ * Exclusively create `path` via temp write + hard-link.
+ * EEXIST (including a pre-existing symlink) fails closed without following it.
+ */
 export async function atomicCreate(
   path: string,
-  content: string
+  content: AtomicCreateContent
 ): Promise<void> {
   const tempPath = `${path}.tmp.${crypto.randomUUID()}`;
   await Bun.write(tempPath, content);
   try {
+    // node:fs/promises link — exclusive create; no Bun equivalent
     await link(tempPath, path);
   } catch (e) {
     await unlink(tempPath).catch(() => {
@@ -78,6 +90,122 @@ export async function createFolderPath(path: string): Promise<void> {
   await mkdir(path, { recursive: true });
 }
 
+/** Sibling staging/backup path beside a user file (never under a different root). */
+export function siblingRefactorPath(
+  path: string,
+  kind: "stage" | "backup",
+  token: string
+): string {
+  return `${path}.gno-rf-${kind}.${token}`;
+}
+
+/**
+ * Exclusively create a stage artifact. Pre-existing symlink/file at stagePath
+ * fails closed (EEXIST) and is never followed/overwritten.
+ */
+export async function writeStagedFileContent(
+  stagePath: string,
+  content: string
+): Promise<void> {
+  await atomicCreate(stagePath, content);
+}
+
+/**
+ * Exclusively copy live bytes into a sibling backup path.
+ * Pre-existing symlink/file at backupPath fails closed (EEXIST).
+ */
+export async function backupFileToSibling(
+  sourcePath: string,
+  backupPath: string
+): Promise<void> {
+  await atomicCreate(backupPath, Bun.file(sourcePath));
+}
+
+/**
+ * Replace an existing path from a staged sibling via rename.
+ * Callers must verify live fingerprints before invoking.
+ */
+export async function commitStagedFileReplace(
+  stagePath: string,
+  targetPath: string
+): Promise<void> {
+  await rename(stagePath, targetPath);
+}
+
+/**
+ * Create a new target from a staged sibling without overwrite.
+ * Uses hard-link create semantics so an occupied target fails closed.
+ */
+export async function commitStagedFileExclusive(
+  stagePath: string,
+  targetPath: string
+): Promise<void> {
+  // node:fs/promises link — exclusive create; no Bun equivalent
+  await link(stagePath, targetPath);
+  await unlink(stagePath).catch(() => {
+    /* stage cleanup best-effort after durable target exists */
+  });
+}
+
+/** @deprecated Prefer commitStagedFileReplace / commitStagedFileExclusive. */
+export async function commitStagedFile(
+  stagePath: string,
+  targetPath: string
+): Promise<void> {
+  await commitStagedFileReplace(stagePath, targetPath);
+}
+
+/**
+ * Restore original bytes by replacing the target path itself (rename),
+ * never following a symlink that may have been swapped onto the target.
+ */
+export async function restoreFileFromBackup(
+  backupPath: string,
+  targetPath: string
+): Promise<void> {
+  const tempPath = `${targetPath}.gno-rf-restore.${crypto.randomUUID()}`;
+  await Bun.write(tempPath, Bun.file(backupPath));
+  try {
+    // node:fs/promises rename — replaces the directory entry (symlink-safe)
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    await unlink(tempPath).catch(() => {
+      /* ignore cleanup errors */
+    });
+    throw error;
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+/** Best-effort cleanup removal; ignores all errors (never used for commit). */
+export async function removePathIfExists(path: string): Promise<void> {
+  // node:fs/promises unlink — structure op, no Bun equivalent
+  await unlink(path).catch(() => {
+    /* ignore cleanup errors */
+  });
+}
+
+/**
+ * Required removal: ignores only ENOENT. Permission/I/O failures throw so
+ * callers cannot report success with both source and target present.
+ */
+export async function removePathRequired(path: string): Promise<void> {
+  // node:fs/promises unlink — structure op, no Bun equivalent
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (isEnoent(error)) return;
+    throw error;
+  }
+}
+
 type TrashFileDeps = {
   homeDir?: string;
   platform?: ReturnType<typeof getPlatform>;