@gmickel/gno 1.30.7 → 1.32.0

package/spec/output-schemas/section-target-create-result.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target-create-result@1.0",
+  "title": "GNO Section Target Create Result",
+  "description": "Response from creating a durable SectionTargetV1 against a stored document. Canonical uri always comes from the resolved document.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["uri", "target"],
+  "properties": {
+    "uri": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Canonical stored document URI"
+    },
+    "target": {
+      "$ref": "gno://schemas/section-target@1.0"
+    }
+  }
+}

package/spec/output-schemas/section-target-resolve-result.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target-resolve-result@1.0",
+  "title": "GNO Section Target Resolve Result",
+  "description": "Conservative section-target resolution result shared by REST and SDK. Citation is present only for navigable exact/recovered statuses. Diagnostics candidates are filtered/capped without truncating identity strings.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics",
+        "citation"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["exact", "recovered"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "#/definitions/diagnostics"
+        },
+        "citation": {
+          "$ref": "#/definitions/citation"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ambiguous", "stale", "missing"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "#/definitions/diagnostics"
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "safePositiveInteger": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "safeNonNegativeInteger": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "diagnostics": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "candidates": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "anchor",
+              "line",
+              "title",
+              "headingPath",
+              "occurrence"
+            ],
+            "properties": {
+              "anchor": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "line": {
+                "$ref": "#/definitions/safePositiveInteger"
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "headingPath": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 6,
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                }
+              },
+              "occurrence": {
+                "$ref": "#/definitions/safePositiveInteger"
+              }
+            }
+          }
+        },
+        "candidateCount": {
+          "$ref": "#/definitions/safeNonNegativeInteger",
+          "description": "Total candidate count before transport filtering/capping"
+        },
+        "candidatesTruncated": {
+          "type": "boolean",
+          "description": "True when any candidate was omitted by bounds filtering or the 32-item cap"
+        }
+      },
+      "dependencies": {
+        "candidates": ["candidateCount", "candidatesTruncated"],
+        "candidateCount": ["candidatesTruncated", "candidates"],
+        "candidatesTruncated": ["candidateCount", "candidates"]
+      }
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "anchor",
+        "title",
+        "lineStart",
+        "lineEnd",
+        "sourceFingerprint"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "anchor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "lineStart": {
+          "$ref": "#/definitions/safePositiveInteger"
+        },
+        "lineEnd": {
+          "$ref": "#/definitions/safePositiveInteger"
+        },
+        "sourceFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/section-target.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target@1.0",
+  "title": "GNO Section Target V1",
+  "description": "Bounded, versioned, content-derived section locator for conservative citation recovery. Does not embed full section bodies.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "document",
+    "anchor",
+    "headingPath",
+    "occurrence",
+    "quote",
+    "sourceFingerprint",
+    "hints"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1",
+      "description": "Section target schema version"
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uri"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Canonical document URI"
+        }
+      }
+    },
+    "anchor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "Human-readable heading anchor at capture time"
+    },
+    "headingPath": {
+      "type": "array",
+      "description": "NFC-normalized heading ancestry including the section title",
+      "minItems": 1,
+      "maxItems": 6,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 512
+      }
+    },
+    "occurrence": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "1-based occurrence among sections with the same headingPath"
+    },
+    "quote": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["exact", "prefix", "suffix"],
+      "properties": {
+        "exact": {
+          "type": "string",
+          "maxLength": 96,
+          "description": "Bounded exact quote (section body preferred, else heading title)"
+        },
+        "prefix": {
+          "type": "string",
+          "maxLength": 32,
+          "description": "Bounded prefix context immediately before exact"
+        },
+        "suffix": {
+          "type": "string",
+          "maxLength": 32,
+          "description": "Bounded suffix context immediately after exact"
+        }
+      }
+    },
+    "sourceFingerprint": {
+      "$ref": "#/definitions/sha256",
+      "description": "SHA-256 hex fingerprint of the full source document content at capture"
+    },
+    "hints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["line", "startOffset", "endOffset"],
+      "description": "Line and code-unit offset hints only; never identity",
+      "properties": {
+        "line": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "1-based heading line at capture"
+        },
+        "startOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "UTF-16 code-unit start offset of the exact quote at capture"
+        },
+        "endOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "UTF-16 code-unit end offset of the exact quote at capture"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  }
+}

package/spec/output-schemas/section.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section@1.0",
+  "title": "GNO MCP Section Tool Result",
+  "description": "Action-discriminated MCP gno_section structured output. Create returns the shared create-result semantics; resolve returns the shared resolve-result semantics (citation only for exact/recovered).",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "action", "uri", "target"],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "create"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "action",
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics",
+        "citation"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "resolve"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["exact", "recovered"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/diagnostics"
+        },
+        "citation": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/citation"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "action",
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "resolve"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ambiguous", "stale", "missing"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/diagnostics"
+        }
+      }
+    }
+  ]
+}

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>;