@gmickel/gno 1.31.0 → 1.32.0

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.31.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.32.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -694,7 +694,7 @@ Open `http://localhost:3000` to:
   configured MCP retrieval without changing client config. Skill installation
   is visible, but client runtime execution cannot be proven automatically
 - **Manage files safely**: Rename, reveal, or move editable files to Trash with explicit index-vs-disk semantics
-- **Refactor files safely**: Move, duplicate, and organize editable notes with reference warnings
+- **Refactor files safely**: Preview and atomically rename or move editable notes while GNO rewrites supported wiki and Markdown references; stale or unsafe plans fail closed
 - **Switch presets**: Change models live without restart
 - **Command palette**: Jump, create, refactor, and section-navigate from one keyboard-first surface
 
@@ -863,9 +863,10 @@ curl http://localhost:3000/api/health
 | `/api/docs`                   | GET    | List documents               |
 | `/api/docs`                   | POST   | Create document              |
 | `/api/docs/:id`               | PUT    | Update document content      |
-| `/api/docs/:id/move`          | POST   | Move editable document       |
+| `/api/docs/:id/rename`        | POST   | Apply confirmed safe rename  |
+| `/api/docs/:id/move`          | POST   | Apply confirmed safe move    |
 | `/api/docs/:id/duplicate`     | POST   | Duplicate editable document  |
-| `/api/docs/:id/refactor-plan` | POST   | Preview file-op warnings     |
+| `/api/docs/:id/refactor-plan` | POST   | Preview reference-safe plan  |
 | `/api/docs/:id/deactivate`    | POST   | Remove from index            |
 | `/api/doc`                    | GET    | Get document content         |
 | `/api/doc/:id/sections`       | GET    | Get document sections        |

package/assets/skill/SKILL.md

@@ -499,6 +499,29 @@ search must include the new note. Browser provenance fields are
 `extractionHash`, `finalBodyHash`, `clipIdentity`, and `previewDigest`—do not
 invent `sourceHash`.
 
+## Reference-Safe Rename and Move
+
+When MCP writes are enabled and the user asks to rename or move an editable
+note, always use the operation-specific two-step tool. Never invent a digest or
+collapse preview and apply into one call.
+
+1. Call `gno_rename_note` or `gno_move_note` with `action: "preview"` and the
+   exact source/destination.
+2. Inspect `canApply`, `safety.blockingReasons`, and `examinedReferences`.
+   Stop and report ambiguous, malformed, unsupported, read-only, occupied,
+   cross-collection, or truncated plans.
+3. Only after explicit user approval, call the same tool with `action: "apply"`,
+   the preview's exact `schemaVersion` and `planDigest`, `confirmation: "apply"`,
+   and `confirm: true`.
+4. Treat `applied_with_sync_pending` as a committed filesystem refactor whose
+   index still needs `gno_sync` or `gno_index`; do not retry the file mutation.
+   For `stale_plan`, preview again instead of reusing the old digest.
+
+Supported wiki and Markdown destinations are rewritten in the same
+all-or-rollback filesystem transaction as the source move. Duplicate and
+create-folder do not retarget inbound references. Authentication alone never
+enables these MCP writes.
+
 ## Collection-specific embedding models
 
 Collections can override the global embedding model with `models.embed`.

package/browser-extension/artifacts/gno-browser-clipper-v1.32.0.zip.sha256

@@ -0,0 +1 @@
+cb5c4bba8cf1252da4e4fc89f1dc01a8df306851cccb50f636d89a6ef3133cff  gno-browser-clipper-v1.32.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.31.0"
+  "version": "1.32.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -3448,6 +3448,25 @@ Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RU
 
 ---
 
+## Workspace file refactors (non-CLI)
+
+Reference-safe note rename and same-collection move use a transport-neutral
+preview/apply contract defined in `src/core/file-refactors.ts` and frozen as:
+
+- `gno://schemas/file-refactor-preview@1.0`
+- `gno://schemas/file-refactor-apply-result@1.0`
+
+Surfaces that adapt the contract are REST/Web UI, SDK, and write-gated MCP
+(`gno_rename_note`, `gno_move_note`). This specification intentionally does
+**not** add a CLI command family or generic action bus for refactors.
+Duplicate-note and create-folder keep their existing shipped semantics and do
+not retarget inbound references.
+
+The contract separates durable filesystem commit/rollback from post-commit
+index convergence. A successful filesystem refactor is never rolled back solely
+because reindexing is temporarily unavailable
+(`applied_with_sync_pending`).
+
 ## See Also
 
 - [MCP Specification](./mcp.md)

package/spec/db/schema.sql

@@ -21,6 +21,7 @@
 --   retrieval_trace_exports/export_traces - Export manifests and trace joins
 --   document_changes - Bounded metadata-only document lifecycle journal
 --   document_change_journal_state - Monotonic cursor/retention boundary
+--   file_refactor_recovery_journal - Content-free rename/move recovery receipts
 
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Schema Metadata
@@ -742,3 +743,57 @@ CREATE TABLE IF NOT EXISTS clipper_capture_idempotency (
 
 CREATE INDEX IF NOT EXISTS idx_clipper_idempotency_created
   ON clipper_capture_idempotency(created_at_ms, grant_id, key_hash);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- File refactor recovery journal (content-free)
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- Durable receipts for multi-file rename/move apply. Stores IDs, digests,
+-- collection/relpaths, phase/state, timestamps, and fingerprints/status only.
+-- Never stores note bodies or replacement content.
+-- Bounded: create prunes oldest terminal receipts (converged/rolled_back/aborted)
+-- under FILE_REFACTOR_JOURNAL_MAX_RECEIPTS; never prunes recovery_required.
+
+CREATE TABLE IF NOT EXISTS file_refactor_recovery_journal (
+  journal_id TEXT PRIMARY KEY,
+  plan_digest TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  operation TEXT NOT NULL
+    CHECK (operation IN ('rename', 'move')),
+  source_rel_path TEXT NOT NULL,
+  target_rel_path TEXT NOT NULL,
+  phase TEXT NOT NULL
+    CHECK (phase IN (
+      'prepared', 'staging', 'committing', 'committed', 'sync_pending',
+      'converged', 'rolling_back', 'rolled_back', 'recovery_required',
+      'aborted'
+    )),
+  phase_ordinal INTEGER NOT NULL CHECK (phase_ordinal >= 0),
+  filesystem_state TEXT NOT NULL
+    CHECK (filesystem_state IN (
+      'unchanged', 'committed', 'rolled_back', 'recovery_required'
+    )),
+  index_state TEXT NOT NULL
+    CHECK (index_state IN (
+      'not_attempted', 'pending', 'converged', 'skipped'
+    )),
+  file_entries_json TEXT NOT NULL
+    CHECK (length(CAST(file_entries_json AS BLOB)) <= 65536),
+  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+  updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= 0),
+  CHECK (length(CAST(journal_id AS BLOB)) BETWEEN 1 AND 128),
+  CHECK (
+    length(plan_digest) = 64
+    AND plan_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+  CHECK (length(CAST(source_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+  CHECK (length(CAST(target_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+  CHECK (updated_at_ms >= created_at_ms)
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_plan_digest
+  ON file_refactor_recovery_journal(plan_digest, updated_at_ms DESC, journal_id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_collection
+  ON file_refactor_recovery_journal(collection, updated_at_ms DESC);

package/spec/mcp.md

@@ -1798,39 +1798,140 @@ Create a folder inside an existing collection (write-enabled).
 
 Rename an editable note in place (write-enabled).
 
+Same-collection rename is covered by the transport-neutral reference-safe
+refactor contract (`src/core/file-refactors.ts`). Preview and apply share one
+versioned schema pair across MCP, REST/SDK, and UI adapters:
+
+- Preview plan: `gno://schemas/file-refactor-preview@1.0`
+- Apply result: `gno://schemas/file-refactor-apply-result@1.0`
+
+The preview enumerates examined wiki/Markdown references with classifications
+and stable reason codes, destination-only edit spans, precondition fingerprints,
+a deterministic `planDigest`, safety summary, and `canApply`. Apply requires the
+exact `planDigest`, confirmation token `apply`, `confirm: true`, and
+`schemaVersion: "1.0"`. Apply never silently preview-and-confirms. Terminal
+statuses are `applied`, `applied_with_sync_pending`, `conflict`, `stale_plan`,
+`unsupported`, and `failed_rolled_back`.
+
+Filesystem commit (moved note + accepted reference rewrites) is an atomic
+all-or-rollback boundary. Index/link convergence runs only after a durable
+filesystem commit and is **not** the same transaction; reindex failure returns
+`applied_with_sync_pending` without rolling back committed files.
+
+MCP annotations remain hints, not authorization. Write gating (`--enable-write`)
+and destructive confirmation (`confirm: true` + `confirmation: "apply"`) still
+apply. No generic action-bus tool is introduced.
+
 **Input Schema:**
 
 ```json
 {
   "type": "object",
-  "properties": {
-    "ref": { "type": "string" },
-    "name": { "type": "string" }
-  },
-  "required": ["ref", "name"]
+  "oneOf": [
+    {
+      "properties": {
+        "action": { "const": "preview" },
+        "ref": { "type": "string" },
+        "name": { "type": "string" }
+      },
+      "required": ["action", "ref", "name"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "action": { "const": "apply" },
+        "ref": { "type": "string" },
+        "name": { "type": "string" },
+        "schemaVersion": { "const": "1.0" },
+        "planDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "confirmation": { "const": "apply" },
+        "confirm": { "const": true }
+      },
+      "required": [
+        "action",
+        "ref",
+        "name",
+        "schemaVersion",
+        "planDigest",
+        "confirmation",
+        "confirm"
+      ],
+      "additionalProperties": false
+    }
+  ]
 }
 ```
 
+**Output Schema:**
+
+- `action=preview` → `gno://schemas/file-refactor-preview@1.0` (content-free plan)
+- `action=apply` → `gno://schemas/file-refactor-apply-result@1.0` (content-free receipt)
+
+Missing or incorrect apply confirmation fails before mutation.
+
 ---
 
 ### gno_move_note
 
 Move an editable note to another folder in the same collection (write-enabled).
 
+Cross-collection moves are out of scope and fail closed with
+`cross_collection_unsupported`. Preview/apply semantics, destination-only edit
+spans, stale-plan protection, and the filesystem-vs-index mutation boundary match
+`gno_rename_note` and use the same schemas:
+
+- Preview plan: `gno://schemas/file-refactor-preview@1.0`
+- Apply result: `gno://schemas/file-refactor-apply-result@1.0`
+
 **Input Schema:**
 
 ```json
 {
   "type": "object",
-  "properties": {
-    "ref": { "type": "string" },
-    "folderPath": { "type": "string" },
-    "name": { "type": "string" }
-  },
-  "required": ["ref", "folderPath"]
+  "oneOf": [
+    {
+      "properties": {
+        "action": { "const": "preview" },
+        "ref": { "type": "string" },
+        "folderPath": { "type": "string" },
+        "name": { "type": "string" }
+      },
+      "required": ["action", "ref", "folderPath"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "action": { "const": "apply" },
+        "ref": { "type": "string" },
+        "folderPath": { "type": "string" },
+        "name": { "type": "string" },
+        "schemaVersion": { "const": "1.0" },
+        "planDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "confirmation": { "const": "apply" },
+        "confirm": { "const": true }
+      },
+      "required": [
+        "action",
+        "ref",
+        "folderPath",
+        "schemaVersion",
+        "planDigest",
+        "confirmation",
+        "confirm"
+      ],
+      "additionalProperties": false
+    }
+  ]
 }
 ```
 
+**Output Schema:**
+
+- `action=preview` → `gno://schemas/file-refactor-preview@1.0` (content-free plan)
+- `action=apply` → `gno://schemas/file-refactor-apply-result@1.0` (content-free receipt)
+
+Missing or incorrect apply confirmation fails before mutation.
+
 ---
 
 ### gno_duplicate_note
@@ -2243,6 +2344,8 @@ Output schemas include version in `$id`:
 
 - `gno://schemas/search-result@1.0`
 - `gno://schemas/capture-receipt@1.0`
+- `gno://schemas/file-refactor-preview@1.0`
+- `gno://schemas/file-refactor-apply-result@1.0`
 
 Clients should check schema version for compatibility.
 

package/spec/output-schemas/file-refactor-apply-result.schema.json

@@ -0,0 +1,305 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/file-refactor-apply-result@1.0",
+  "title": "GNO File Refactor Apply Result",
+  "description": "Terminal result for reference-safe rename/move apply. Filesystem commit/rollback is modeled separately from post-commit index convergence; recovery metadata is content-free. Status discriminates valid filesystem/index/reason combinations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "planDigest",
+    "operation",
+    "source",
+    "target",
+    "filesystem",
+    "indexConvergence"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "applied",
+        "applied_with_sync_pending",
+        "conflict",
+        "stale_plan",
+        "unsupported",
+        "failed_rolled_back"
+      ]
+    },
+    "planDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "operation": {
+      "type": "string",
+      "enum": ["rename", "move"]
+    },
+    "source": {
+      "$ref": "#/definitions/documentRef"
+    },
+    "target": {
+      "$ref": "#/definitions/documentRef"
+    },
+    "reasonCode": {
+      "$ref": "#/definitions/reasonCode"
+    },
+    "filesystem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": ["committed", "rolled_back", "unchanged", "recovery_required"]
+        },
+        "recoveryJournalId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Opaque journal id only — never embeds note content"
+        }
+      }
+    },
+    "indexConvergence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": ["converged", "pending", "not_attempted", "skipped"]
+        },
+        "recoveryInstruction": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Content-free instruction to finish index convergence"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "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
+        }
+      }
+    },
+    "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"
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "const": "applied"
+          }
+        },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "reasonCode": false,
+          "filesystem": {
+            "type": "object",
+            "properties": {
+              "state": {
+                "const": "committed"
+              }
+            }
+          },
+          "indexConvergence": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["state"],
+            "properties": {
+              "state": {
+                "const": "converged"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "const": "applied_with_sync_pending"
+          }
+        },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "required": ["reasonCode"],
+        "properties": {
+          "reasonCode": {
+            "const": "sync_pending"
+          },
+          "filesystem": {
+            "type": "object",
+            "properties": {
+              "state": {
+                "const": "committed"
+              }
+            }
+          },
+          "indexConvergence": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["state", "recoveryInstruction"],
+            "properties": {
+              "state": {
+                "const": "pending"
+              },
+              "recoveryInstruction": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "enum": ["conflict", "stale_plan", "unsupported"]
+          }
+        },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "required": ["reasonCode"],
+        "properties": {
+          "filesystem": {
+            "type": "object",
+            "properties": {
+              "state": {
+                "const": "unchanged"
+              }
+            }
+          },
+          "indexConvergence": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["state"],
+            "properties": {
+              "state": {
+                "enum": ["not_attempted", "skipped"]
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "const": "stale_plan"
+          }
+        },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "required": ["reasonCode"],
+        "properties": {
+          "reasonCode": {
+            "const": "stale_plan"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "const": "failed_rolled_back"
+          }
+        },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "required": ["reasonCode"],
+        "properties": {
+          "filesystem": {
+            "type": "object",
+            "properties": {
+              "state": {
+                "enum": ["rolled_back", "recovery_required"]
+              }
+            }
+          },
+          "indexConvergence": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["state"],
+            "properties": {
+              "state": {
+                "enum": ["not_attempted", "skipped"]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}