@gmickel/gno 1.31.0 → 1.33.0

package/src/mcp/tools/workspace-write.ts

@@ -8,6 +8,7 @@
 import { mkdir } from "node:fs/promises";
 // node:path for dirname/join (no Bun path utils)
 import { dirname, join } from "node:path";
+import { z } from "zod";
 
 import type { Collection } from "../../config/types";
 import type { ToolContext } from "../server";
@@ -15,17 +16,22 @@ import type { ToolContext } from "../server";
 import { getDocumentCapabilities } from "../../core/document-capabilities";
 import { MCP_ERRORS } from "../../core/errors";
 import { withWriteLock } from "../../core/file-lock";
+import { copyFilePath, createFolderPath } from "../../core/file-ops";
 import {
-  copyFilePath,
-  createFolderPath,
-  renameFilePath,
-} from "../../core/file-ops";
-import {
+  applyCanonicalFileRefactor,
+  assertFileRefactorSyncConverged,
+  buildCanonicalRefactorPlan,
+  buildDurableFileRefactorApplyDeps,
   buildRefactorWarnings,
+  FILE_REFACTOR_APPLY_CONFIRMATION,
+  FILE_REFACTOR_SCHEMA_VERSION,
+  parseRefactorApplyConfirmation,
   planCreateFolder,
   planDuplicateRefactor,
-  planMoveRefactor,
-  planRenameRefactor,
+  resolveMoveTarget,
+  resolveRenameTarget,
+  type FileRefactorApplyResult,
+  type FileRefactorPreviewPlan,
 } from "../../core/file-refactors";
 import { recordContentMutation } from "../../core/mutation-generations";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
@@ -37,23 +43,72 @@ interface CreateFolderInput {
   parentPath?: string;
 }
 
-interface RenameNoteInput {
-  ref: string;
-  name: string;
-}
-
-interface MoveNoteInput {
-  ref: string;
-  folderPath: string;
-  name?: string;
-}
-
 interface DuplicateNoteInput {
   ref: string;
   folderPath?: string;
   name?: string;
 }
 
+const refactorPreviewActionSchema = z.literal("preview");
+const refactorApplyActionSchema = z.literal("apply");
+
+export const renameNoteInputSchema = z.discriminatedUnion("action", [
+  z.object({
+    action: refactorPreviewActionSchema,
+    ref: z.string().min(1, "ref cannot be empty"),
+    name: z.string().min(1, "name cannot be empty"),
+  }),
+  z.object({
+    action: refactorApplyActionSchema,
+    ref: z.string().min(1, "ref cannot be empty"),
+    name: z.string().min(1, "name cannot be empty"),
+    schemaVersion: z.literal(FILE_REFACTOR_SCHEMA_VERSION),
+    planDigest: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/, "planDigest must be a lowercase SHA-256"),
+    confirmation: z.literal(FILE_REFACTOR_APPLY_CONFIRMATION),
+    confirm: z.literal(true),
+  }),
+]);
+
+export const moveNoteInputSchema = z.discriminatedUnion("action", [
+  z.object({
+    action: refactorPreviewActionSchema,
+    ref: z.string().min(1, "ref cannot be empty"),
+    folderPath: z.string().min(1, "folderPath cannot be empty"),
+    name: z.string().optional(),
+  }),
+  z.object({
+    action: refactorApplyActionSchema,
+    ref: z.string().min(1, "ref cannot be empty"),
+    folderPath: z.string().min(1, "folderPath cannot be empty"),
+    name: z.string().optional(),
+    schemaVersion: z.literal(FILE_REFACTOR_SCHEMA_VERSION),
+    planDigest: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/, "planDigest must be a lowercase SHA-256"),
+    confirmation: z.literal(FILE_REFACTOR_APPLY_CONFIRMATION),
+    confirm: z.literal(true),
+  }),
+]);
+
+export type RenameNoteInput = z.infer<typeof renameNoteInputSchema>;
+export type MoveNoteInput = z.infer<typeof moveNoteInputSchema>;
+
+export const RENAME_NOTE_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const;
+
+export const MOVE_NOTE_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const;
+
 function resolveCollection(ctx: ToolContext, name: string): Collection {
   const normalized = name.trim().toLowerCase();
   const collection = ctx.collections.find((entry) => entry.name === normalized);
@@ -156,6 +211,136 @@ function ensureEditable(doc: {
       }`
     );
   }
+  return capabilities;
+}
+
+function requireWriteEnabled(ctx: ToolContext): void {
+  if (!ctx.enableWrite) {
+    throw new Error("Write tools disabled. Start MCP with --enable-write.");
+  }
+}
+
+function requireApplyConfirmation(args: {
+  schemaVersion: unknown;
+  planDigest: unknown;
+  confirmation: unknown;
+  confirm: unknown;
+}) {
+  if (args.confirm !== true) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_INPUT.code}: confirm must be true to apply`
+    );
+  }
+  const parsed = parseRefactorApplyConfirmation(args);
+  if ("error" in parsed) {
+    throw new Error(`${parsed.error}: ${parsed.message}`);
+  }
+  return parsed;
+}
+
+function formatPreviewSummary(plan: FileRefactorPreviewPlan): string {
+  return `Preview ${plan.operation}: ${plan.source.relPath} → ${plan.target.relPath} (digest ${plan.planDigest.slice(0, 12)}…, canApply=${plan.canApply})`;
+}
+
+function formatApplySummary(result: FileRefactorApplyResult): string {
+  return `${result.operation} ${result.status}: ${result.source.relPath} → ${result.target.relPath}`;
+}
+
+async function previewOrApplyRename(
+  args: RenameNoteInput,
+  ctx: ToolContext
+): Promise<FileRefactorPreviewPlan | FileRefactorApplyResult> {
+  requireWriteEnabled(ctx);
+  const doc = await resolveDocByRef(ctx, args.ref);
+  const capabilities = ensureEditable(doc);
+  const collection = resolveCollection(ctx, doc.collection);
+  const target = resolveRenameTarget({
+    collection: collection.name,
+    currentRelPath: doc.relPath,
+    nextName: args.name,
+  });
+  const plan = await buildCanonicalRefactorPlan({
+    operation: "rename",
+    doc,
+    collection,
+    sourceFullPath: join(collection.path, doc.relPath),
+    target,
+    store: ctx.store,
+    sourceEditable: capabilities.editable,
+  });
+
+  if (args.action === "preview") {
+    return plan;
+  }
+
+  const confirmation = requireApplyConfirmation(args);
+  // Collection-scoped lock lives inside applyFileRefactor — do not wrap with
+  // ctx.writeLockPath (avoids double-locking incompatible with REST/SDK).
+  return applyCanonicalFileRefactor({
+    plan,
+    confirmation,
+    deps: buildDurableFileRefactorApplyDeps({
+      collection,
+      store: ctx.store,
+      syncAfterCommit: async () => {
+        const syncResult = await defaultSyncService.syncCollection(
+          collection,
+          ctx.store,
+          withContentTypeRules({ runUpdateCmd: false }, ctx.config)
+        );
+        assertFileRefactorSyncConverged(syncResult);
+        recordContentMutation(syncResult, ctx.markContentMutation);
+      },
+    }),
+  });
+}
+
+async function previewOrApplyMove(
+  args: MoveNoteInput,
+  ctx: ToolContext
+): Promise<FileRefactorPreviewPlan | FileRefactorApplyResult> {
+  requireWriteEnabled(ctx);
+  const doc = await resolveDocByRef(ctx, args.ref);
+  const capabilities = ensureEditable(doc);
+  const collection = resolveCollection(ctx, doc.collection);
+  const target = resolveMoveTarget({
+    collection: collection.name,
+    currentRelPath: doc.relPath,
+    folderPath: args.folderPath,
+    nextName: args.name,
+  });
+  const plan = await buildCanonicalRefactorPlan({
+    operation: "move",
+    doc,
+    collection,
+    sourceFullPath: join(collection.path, doc.relPath),
+    target,
+    store: ctx.store,
+    sourceEditable: capabilities.editable,
+  });
+
+  if (args.action === "preview") {
+    return plan;
+  }
+
+  const confirmation = requireApplyConfirmation(args);
+  return applyCanonicalFileRefactor({
+    plan,
+    confirmation,
+    deps: buildDurableFileRefactorApplyDeps({
+      collection,
+      store: ctx.store,
+      syncAfterCommit: async () => {
+        const syncResult = await defaultSyncService.syncCollection(
+          collection,
+          ctx.store,
+          withContentTypeRules({ runUpdateCmd: false }, ctx.config)
+        );
+        assertFileRefactorSyncConverged(syncResult);
+        recordContentMutation(syncResult, ctx.markContentMutation);
+      },
+    }),
+  });
 }
 
 export function handleCreateFolder(
@@ -166,9 +351,7 @@ export function handleCreateFolder(
     ctx,
     "gno_create_folder",
     async () => {
-      if (!ctx.enableWrite) {
-        throw new Error("Write tools disabled. Start MCP with --enable-write.");
-      }
+      requireWriteEnabled(ctx);
 
       return withWriteLock(ctx.writeLockPath, async () => {
         const collection = resolveCollection(ctx, args.collection);
@@ -196,40 +379,11 @@ export function handleRenameNote(
   return runTool(
     ctx,
     "gno_rename_note",
-    async () => {
-      if (!ctx.enableWrite) {
-        throw new Error("Write tools disabled. Start MCP with --enable-write.");
-      }
-
-      return withWriteLock(ctx.writeLockPath, async () => {
-        const doc = await resolveDocByRef(ctx, args.ref);
-        ensureEditable(doc);
-        const collection = resolveCollection(ctx, doc.collection);
-        const plan = planRenameRefactor({
-          collection: collection.name,
-          currentRelPath: doc.relPath,
-          nextName: args.name,
-        });
-        const currentPath = join(collection.path, doc.relPath);
-        const nextPath = join(collection.path, plan.nextRelPath);
-        await renameFilePath(currentPath, nextPath);
-        const syncResult = await defaultSyncService.syncCollection(
-          collection,
-          ctx.store,
-          withContentTypeRules({ runUpdateCmd: false }, ctx.config)
-        );
-        recordContentMutation(syncResult, ctx.markContentMutation);
-        return {
-          uri: plan.nextUri,
-          relPath: plan.nextRelPath,
-          warnings: buildRefactorWarnings(
-            await getRefactorSnapshot(ctx, doc.id),
-            { filenameChanged: true }
-          ).warnings,
-        };
-      });
-    },
-    (data) => `Renamed note to ${data.relPath}`
+    async () => previewOrApplyRename(args, ctx),
+    (data) =>
+      "planDigest" in data && "canApply" in data
+        ? formatPreviewSummary(data)
+        : formatApplySummary(data)
   );
 }
 
@@ -240,45 +394,11 @@ export function handleMoveNote(
   return runTool(
     ctx,
     "gno_move_note",
-    async () => {
-      if (!ctx.enableWrite) {
-        throw new Error("Write tools disabled. Start MCP with --enable-write.");
-      }
-
-      return withWriteLock(ctx.writeLockPath, async () => {
-        const doc = await resolveDocByRef(ctx, args.ref);
-        ensureEditable(doc);
-        const collection = resolveCollection(ctx, doc.collection);
-        const plan = planMoveRefactor({
-          collection: collection.name,
-          currentRelPath: doc.relPath,
-          folderPath: args.folderPath,
-          nextName: args.name,
-        });
-        const currentPath = join(collection.path, doc.relPath);
-        const nextPath = join(collection.path, plan.nextRelPath);
-        await mkdir(dirname(nextPath), { recursive: true });
-        await renameFilePath(currentPath, nextPath);
-        const syncResult = await defaultSyncService.syncCollection(
-          collection,
-          ctx.store,
-          withContentTypeRules({ runUpdateCmd: false }, ctx.config)
-        );
-        recordContentMutation(syncResult, ctx.markContentMutation);
-        return {
-          uri: plan.nextUri,
-          relPath: plan.nextRelPath,
-          warnings: buildRefactorWarnings(
-            await getRefactorSnapshot(ctx, doc.id),
-            {
-              folderChanged: true,
-              filenameChanged: Boolean(args.name),
-            }
-          ).warnings,
-        };
-      });
-    },
-    (data) => `Moved note to ${data.relPath}`
+    async () => previewOrApplyMove(args, ctx),
+    (data) =>
+      "planDigest" in data && "canApply" in data
+        ? formatPreviewSummary(data)
+        : formatApplySummary(data)
   );
 }
 
@@ -290,9 +410,7 @@ export function handleDuplicateNote(
     ctx,
     "gno_duplicate_note",
     async () => {
-      if (!ctx.enableWrite) {
-        throw new Error("Write tools disabled. Start MCP with --enable-write.");
-      }
+      requireWriteEnabled(ctx);
 
       return withWriteLock(ctx.writeLockPath, async () => {
         const doc = await resolveDocByRef(ctx, args.ref);

package/src/publish/artifact-asset-codec.ts

@@ -0,0 +1,75 @@
+/**
+ * Synchronous SHA-256 + base64 helpers for publish assets.
+ * Bun.CryptoHasher for digests; browser-safe atob for base64 decode parity with gno.sh.
+ *
+ * @module src/publish/artifact-asset-codec
+ */
+
+/** Synchronous SHA-256 hex digest over raw bytes (Bun-native). */
+export const sha256BytesHex = (bytes: Uint8Array): string => {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(bytes);
+  return hasher.digest("hex");
+};
+
+const BASE64_PATTERN =
+  /^(?:[a-zA-Z0-9+/]{4})*(?:[a-zA-Z0-9+/]{2}==|[a-zA-Z0-9+/]{3}=)?$/u;
+
+/**
+ * Encode raw bytes to standard base64 without Node Buffer.
+ * Prefers Bun/Web Uint8Array.toBase64(); falls back to btoa for parity with decode.
+ */
+export const encodeBytesToBase64 = (bytes: Uint8Array): string => {
+  if (typeof bytes.toBase64 === "function") {
+    return bytes.toBase64();
+  }
+  const CHUNK = 0x8000;
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += CHUNK) {
+    const slice = bytes.subarray(offset, offset + CHUNK);
+    binary += String.fromCharCode(...slice);
+  }
+  return btoa(binary);
+};
+
+/** Decode standard base64 without Buffer (uses atob). */
+export const decodeBase64ToBytes = (
+  data: string
+): { ok: true; bytes: Uint8Array } | { ok: false } => {
+  if (!BASE64_PATTERN.test(data) || data.length === 0) return { ok: false };
+  try {
+    const binary = atob(data);
+    if (binary.length === 0 && data.replace(/=+$/u, "").length > 0) {
+      return { ok: false };
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return { ok: true, bytes };
+  } catch {
+    return { ok: false };
+  }
+};
+
+const UTF8 = new TextEncoder();
+
+export const measureSerializedUploadBytes = (serializedBody: string): number =>
+  UTF8.encode(serializedBody).byteLength;
+
+/**
+ * Canonical on-disk/upload serialization for publish artifacts.
+ *
+ * Byte-budget enforcement and every artifact writer must use this exact
+ * representation so `finalUploadBytes` describes the bytes handed to gno.sh.
+ */
+export const serializePublishArtifact = (artifact: unknown): string => {
+  const serialized = JSON.stringify(artifact, null, 2);
+  if (serialized === undefined) {
+    throw new TypeError("Publish artifact is not JSON-serializable");
+  }
+  return serialized;
+};
+
+export const measureArtifactUploadBytes = (artifact: unknown): number =>
+  measureSerializedUploadBytes(serializePublishArtifact(artifact));

package/src/publish/artifact-asset-contract.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared publish-asset contract vocabulary (producer/consumer).
+ *
+ * @module src/publish/artifact-asset-contract
+ */
+
+export const MAX_PUBLISH_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+/** Schema bounds for asset reference sourceRef (publish-artifact.schema.json). */
+export const MIN_SOURCE_REF_LENGTH = 1;
+export const MAX_SOURCE_REF_LENGTH = 1024;
+
+export const BUNDLED_RASTER_ASSETS_CAPABILITY =
+  "bundled-raster-assets@1" as const;
+
+export const KNOWN_PUBLISH_REQUIRED_CAPABILITIES = [
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+] as const;
+
+/** Schema bounds for requiredCapabilities entries (publish-artifact.schema.json). */
+export const MIN_REQUIRED_CAPABILITY_LENGTH = 1;
+export const MAX_REQUIRED_CAPABILITY_LENGTH = 128;
+
+export type KnownPublishRequiredCapability =
+  (typeof KNOWN_PUBLISH_REQUIRED_CAPABILITIES)[number];
+
+export const SUPPORTED_RASTER_MEDIA_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+] as const;
+
+export type SupportedRasterMediaType =
+  (typeof SUPPORTED_RASTER_MEDIA_TYPES)[number];
+
+export const MAX_RASTER_DIMENSION_PX = 16_384;
+export const MIN_RASTER_DIMENSION_PX = 1;
+
+/** Strict sentinel: scheme + lowercase SHA-256 hex asset id. */
+export const GNO_ASSET_SENTINEL_PATTERN = /^gno-asset:([a-f0-9]{64})$/u;
+export const GNO_ASSET_SENTINEL_PREFIX = "gno-asset:";
+
+export const PUBLISH_ASSET_NOTE_SLUG_PATTERN =
+  /^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$/u;
+
+export const PUBLISH_ASSET_VISIBILITY = {
+  public: {
+    class: "public",
+    delivery: "immutable-public-url",
+    storage: "private-until-public-commit",
+    notes:
+      "Validated assets may use immutable public URLs only after the share is classified public.",
+  },
+  "secret-link": {
+    class: "secret",
+    delivery: "capability-authorized",
+    storage: "private",
+    forbids: ["public-object-url", "presigned-url-as-sole-authorization"],
+    notes:
+      "Secret is an authorization boundary; private storage delivery requires the secret-share capability.",
+  },
+  encrypted: {
+    class: "encrypted",
+    delivery: "client-blob-url",
+    storage: "none-plaintext",
+    assetPlacement: "encrypted-client-payload",
+    notes:
+      "Plaintext image bytes remain inside the encrypted client payload; Blob URLs are revoked on replacement/unmount.",
+  },
+} as const;
+
+export const PUBLISH_ASSET_LIFECYCLE_TERMINALS = [
+  "committed",
+  "rolled_back",
+  "deleted",
+  "orphan_cleaned",
+  "idempotent_noop",
+] as const;
+
+export type PublishAssetLifecycleTerminal =
+  (typeof PUBLISH_ASSET_LIFECYCLE_TERMINALS)[number];
+
+export const PUBLISH_ASSET_DIAGNOSTIC_CODES = [
+  "ASSET_MISSING",
+  "ASSET_CONFLICT",
+  "ASSET_SENTINEL_RAW",
+  "ASSET_SENTINEL_UNRESOLVED",
+  "ASSET_SENTINEL_INVALID",
+  "ASSET_TRAVERSAL",
+  "ASSET_MIME_SPOOF",
+  "ASSET_OVERSIZE",
+  "ASSET_CORRUPT",
+  "ASSET_UNSUPPORTED_FORMAT",
+  "ASSET_DIMENSION_INVALID",
+  "CAPABILITY_UNSUPPORTED",
+  "ENVELOPE_OVERSIZE",
+] as const;
+
+export type PublishAssetDiagnosticCode =
+  (typeof PUBLISH_ASSET_DIAGNOSTIC_CODES)[number];
+
+export interface PublishArtifactAssetReference {
+  noteSlug: string;
+  sourceRef: string;
+}
+
+export interface PublishArtifactAsset {
+  byteLength: number;
+  data: string;
+  encoding: "base64";
+  height: number;
+  id: string;
+  mediaType: string;
+  references: Array<PublishArtifactAssetReference>;
+  sha256: string;
+  width: number;
+}
+
+export interface PublishAssetDiagnostic {
+  code: PublishAssetDiagnosticCode;
+  message: string;
+}
+
+export type PublishAssetClassification =
+  | "asset-free"
+  | "bundled-raster-v1"
+  | "encrypted-client-payload";
+
+export type PublishAssetContractResult =
+  | { ok: true; classification: PublishAssetClassification }
+  | { ok: false; diagnostic: PublishAssetDiagnostic };
+
+export interface ValidatePublishAssetContractOptions {
+  /** Exact UTF-8 byte length of the final upload body when already serialized. */
+  serializedUploadBytes?: number;
+}
+
+export const ASSET_DESCRIPTOR_KEYS = [
+  "byteLength",
+  "data",
+  "encoding",
+  "height",
+  "id",
+  "mediaType",
+  "references",
+  "sha256",
+  "width",
+] as const;
+
+export const ASSET_REFERENCE_KEYS = ["noteSlug", "sourceRef"] as const;