feat(core,editor): editor namespace polish + SkillPublishResult.files (#16673)

NikAiyer · Mastra Code (anthropic/claude-opus-4-7) · web-flow · commit 19018f05722a · 2026-05-18T13:35:33.000-05:00
## Summary Carves PARA-3 (Option B + D) from the `yj/magnificent-marquess` feature branch — a small, plumbing-only slice of editor namespace fixes that don't depend on STACK-1 (server permission foundation) or the agent-builder runtime. This is foundation work for the agent-builder feature branch but ships independently with no user-visible behavior changes. ## What's in this PR ### `@mastra/core` (publish.ts) - `SkillPublishResult` now includes a `files` field with the full skill file tree and base64-encoded blob content (`StorageSkillFileNode[]`). - Adds `parseSkillSnapshotFromFiles()` helper and `SkillSnapshotFile` type for parsing skill snapshot frontmatter from flat file lists. ### `@mastra/editor` - **base.ts**: `CrudEditorNamespace.clearCache(id)` always calls `onCacheEvict(id)`, even when the entry wasn't cached. Lets subclasses clean up runtime registries (e.g. `mastra.#agents`) for version-specific lookups that bypass the editor cache. - **skill.ts**: Stores the new `files` field on publish, and strips `undefined` keys from the snapshot before `update()` so libsql/pg adapters don't reject `undefined` as a bind argument. - **workspace.ts**: Adds `snapshotFromWorkspace()` and `serializeFilesystem()` — the reverse of `hydrateSnapshotToWorkspace()` — to round-trip a live `Workspace` instance (`CompositeFilesystem` mounts, sandbox provider, tools config) into a `StorageWorkspaceSnapshotType` for persistence. ## What's NOT in this PR Deferred to later PRs (Option A, agent-builder-bound): - `agent.ts` namespace builder defaults / model policy / browser refs / visibility (~241 lines) - `favorites.ts` namespace + tests (STACK-3) - `MastraEditor` class extensions (`__browsers`, `__builderConfig`, `ensureBuilderWorkspaces()`, etc.) - `IMastraEditor` browser/builder method implementations - `BrowserProvider` type, `StorageBrowserRef`, `MastraBrowser` ## Dependencies - Branches off `main`, no STACK-1 dependency. - No runtime impact on existing users: - `SkillPublishResult.files` is purely additive — existing `{ snapshot, tree }` destructures keep working. - `clearCache()` change is a no-op for subclasses that don't override `onCacheEvict()`. - `snapshotFromWorkspace()` is a new method, no existing callers. ## Test plan - `pnpm --filter @mastra/core typecheck` — clean - `pnpm --filter @mastra/editor typecheck` — clean - `pnpm --filter @mastra/editor test` — 372 passed / 13 skipped (385 total) ## Changesets - `silly-wolves-dance.md` — `@mastra/core` minor (publish.ts `files` field + helpers) - `brave-tigers-cheer.md` — `@mastra/editor` minor (namespace polish)  ## ELI5 This PR improves how the editor handles skill files and workspace snapshots: it records the full file tree for published skills, makes cache eviction reliably trigger cleanup hooks, and adds a way to serialize a live workspace for storage. These are internal plumbing changes to prepare for agent-builder work and don't change user-facing behavior. --- ## Changes Summary ### `@mastra/core` – `packages/core/src/workspace/skills/publish.ts` - Added `files: StorageSkillFileNode[]` to `SkillPublishResult` — a UI-facing nested file tree with base64-encoded content for each file. - Exported `parseSkillSnapshotFromFiles(files: SkillSnapshotFile[])` to parse SKILL.md frontmatter and derive denormalized snapshot fields from a flat file list; introduced the `SkillSnapshotFile` type. - `collectSkillForPublish()` / `publishSkillFromSource()` now build the nested file nodes (including base64 blobs for binary files) and return `files`; missing SKILL.md is rethrown with a clearer error. ### `@mastra/editor` – `packages/editor/src/namespaces/base.ts` - `CrudEditorNamespace.clearCache(id)` now always calls `onCacheEvict(id)` even when the id wasn't present in the cache, allowing subclasses to perform runtime cleanup for entries that may bypass the cache. ### `@mastra/editor` – `packages/editor/src/namespaces/skill.ts` - `EditorSkillNamespace.publish` captures the new `files` from `publishSkillFromSource()` and persists it on the skill record. - Before calling `skillStore.update()`, builds a `snapshotUpdate` object that strips keys with `undefined` values to avoid adapter bind errors (libsql/pg). ### `@mastra/editor` – `packages/editor/src/namespaces/workspace.ts` - Added `snapshotFromWorkspace(workspace: Workspace): Promise<StorageWorkspaceSnapshotType>` to serialize a live Workspace into a storage snapshot. - Added `serializeFilesystem()` helper to serialize primary or mounted filesystems, calling `fs.getInfo()` when available to preserve provider metadata. - Serializes sandbox info via `sandbox.getInfo()` (when present) and copies static workspace tools settings (`enabled`, `requireApproval`) into the stored tools config. --- ## Compatibility & Safety - Additive, backward-compatible API change: `SkillPublishResult.files` is optional/additive for callers that ignore it. - `clearCache()` behavior is a no-op for subclasses that don't override `onCacheEvict()`. - `snapshotFromWorkspace()` is new and has no existing callers. - No STACK-1 dependency; branches off main. - Typechecks pass for `@mastra/core` and `@mastra/editor`. Tests: 372 passed / 13 skipped.  [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16673?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)   --------- Co-authored-by: Mastra Code (anthropic/claude-opus-4-7) <noreply@mastra.ai>
diff --git a/.changeset/brave-tigers-cheer.md b/.changeset/brave-tigers-cheer.md
@@ -0,0 +1,17 @@
+---
+'@mastra/editor': minor
+---
+
+`EditorWorkspaceNamespace` can now snapshot a live `Workspace` for persistence — the reverse of `hydrateSnapshotToWorkspace()`:
+
+```ts
+const snapshot = await editor.workspace.snapshotFromWorkspace(runtimeWorkspace);
+await editor.workspace.create({ id: 'my-workspace', ...snapshot });
+```
+
+`snapshotFromWorkspace()` is `async` and awaits `sandbox.getInfo()` and `filesystem.getInfo()` so async providers like `CompositeFilesystem` keep their mount metadata in the stored config.
+
+Also includes two smaller behavioral fixes:
+
+- `EditorSkillNamespace.publishSkillFromSource()` stores the new `files` field on the published skill version and strips `undefined` keys before calling `update()` (libsql/pg adapters reject `undefined` bind arguments).
+- `CrudEditorNamespace.clearCache(id)` always calls `onCacheEvict(id)`, even when the entity wasn't cached, so subclasses can clean up runtime registries for version-specific lookups that bypass the editor cache.
diff --git a/.changeset/silly-wolves-dance.md b/.changeset/silly-wolves-dance.md
@@ -0,0 +1,21 @@
+---
+'@mastra/core': minor
+---
+
+`publishSkillFromSource()` (and `collectSkillForPublish()`) now return a `files` field containing the full skill source as a tree of `StorageSkillFileNode` entries with base64-encoded blob content — handy for storing a UI-facing copy of a skill alongside its content-addressable tree:
+
+```ts
+const { snapshot, tree, files } = await publishSkillFromSource({ source });
+// files: StorageSkillFileNode[] — name, mimeType, base64 content per node
+```
+
+Existing callers that only destructure `{ snapshot, tree }` are unaffected; the field is additive.
+
+Also adds `parseSkillSnapshotFromFiles()` for parsing skill snapshot frontmatter from a flat file list (used by the registry install flow):
+
+```ts
+import { parseSkillSnapshotFromFiles, type SkillSnapshotFile } from '@mastra/core/workspace';
+
+const files: SkillSnapshotFile[] = [{ path: 'SKILL.md', content: '...' }, ...];
+const snapshot = parseSkillSnapshotFromFiles(files);
+```
diff --git a/packages/core/src/workspace/skills/publish.ts b/packages/core/src/workspace/skills/publish.ts
@@ -5,6 +5,7 @@ import type {
   SkillVersionTree,
   SkillVersionTreeEntry,
   StorageBlobEntry,
+  StorageSkillFileNode,
   StorageSkillSnapshotType,
 } from '../../storage/types';
 import type { SkillSource, SkillSourceEntry } from './skill-source';
@@ -20,6 +21,8 @@ export interface SkillPublishResult {
   tree: SkillVersionTree;
   /** Blob entries to store (already deduplicated by hash) */
   blobs: StorageBlobEntry[];
+  /** UI-facing nested file tree (folders + files with content) for the stored skill record */
+  files: StorageSkillFileNode[];
 }
 
 // =============================================================================
@@ -144,10 +147,99 @@ function collectSubdirPaths(allPaths: string[], subdir: string): string[] {
   return allPaths.filter(p => p.startsWith(prefix)).map(p => p.substring(prefix.length));
 }
 
+/**
+ * Build a nested folder/file tree from a flat list of walked files for the
+ * UI-facing `files` column on the stored skill record. Binary file content is
+ * base64-encoded so it can round-trip through the string-typed `content` field.
+ */
+function buildSkillFileNodes(files: WalkedFile[]): StorageSkillFileNode[] {
+  const root: StorageSkillFileNode[] = [];
+
+  for (const file of files) {
+    const segments = file.path.split('/').filter(Boolean);
+    if (segments.length === 0) continue;
+
+    let cursor = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i]!;
+      let folder = cursor.find(node => node.type === 'folder' && node.name === segment);
+      if (!folder) {
+        folder = { name: segment, type: 'folder', children: [] };
+        cursor.push(folder);
+      }
+      if (!folder.children) folder.children = [];
+      cursor = folder.children;
+    }
+
+    const fileName = segments[segments.length - 1]!;
+    const content = file.isBinary
+      ? (Buffer.isBuffer(file.content) ? file.content : Buffer.from(file.content as string)).toString('base64')
+      : (file.content as string);
+    cursor.push({ name: fileName, type: 'file', content });
+  }
+
+  return root;
+}
+
 // =============================================================================
 // Public API
 // =============================================================================
 
+/**
+ * A flat file entry used by snapshot parsing helpers.
+ * Path is the skill-relative path (e.g. `SKILL.md`, `references/foo.md`).
+ */
+export interface SkillSnapshotFile {
+  path: string;
+  content: string | Buffer;
+}
+
+/**
+ * Parse a flat array of skill files into a denormalized snapshot.
+ *
+ * Finds `SKILL.md`, parses its YAML frontmatter into structured fields
+ * (name, description, license, compatibility, metadata), and uses the
+ * markdown body as `instructions`. Discovers `references/`, `scripts/`,
+ * and `assets/` subdirectory paths from the file list.
+ *
+ * Used by both the publish flow (which has files from a SkillSource walk)
+ * and the registry install flow (which has files fetched from an external
+ * registry like skills.sh). The Agent Skills spec puts metadata in
+ * frontmatter and agent-facing prose in the body — this helper enforces
+ * that split so frontmatter never leaks into the runtime instructions.
+ *
+ * @throws if `SKILL.md` is missing from the file list
+ */
+export function parseSkillSnapshotFromFiles(files: SkillSnapshotFile[]): Omit<StorageSkillSnapshotType, 'tree'> {
+  const skillMdFile = files.find(f => f.path === 'SKILL.md');
+  if (!skillMdFile) {
+    throw new Error('SKILL.md not found in skill files');
+  }
+
+  const skillMdContent =
+    typeof skillMdFile.content === 'string' ? skillMdFile.content : skillMdFile.content.toString('utf-8');
+  const parsed = matter(skillMdContent);
+  const frontmatter = parsed.data;
+  const instructions = parsed.content.trim();
+
+  const allPaths = files.map(f => f.path);
+  const references = collectSubdirPaths(allPaths, 'references');
+  const scripts = collectSubdirPaths(allPaths, 'scripts');
+  const assets = collectSubdirPaths(allPaths, 'assets');
+
+  return {
+    name: frontmatter.name,
+    description: frontmatter.description,
+    instructions,
+    license: frontmatter.license,
+    compatibility: frontmatter.compatibility,
+    metadata: frontmatter.metadata,
+    ...(references.length > 0 ? { references } : {}),
+    ...(scripts.length > 0 ? { scripts } : {}),
+    ...(assets.length > 0 ? { assets } : {}),
+  };
+}
+
 /**
  * Collect a skill from a SkillSource for publishing.
  * Walks the skill directory, hashes all files, parses SKILL.md frontmatter,
@@ -216,37 +308,21 @@ export async function collectSkillForPublish(source: SkillSource, skillPath: str
 
   const tree: SkillVersionTree = { entries: treeEntries };
   const blobs = Array.from(blobMap.values());
+  const fileNodes = buildSkillFileNodes(files);
 
-  // 3. Parse SKILL.md with gray-matter for denormalized fields
-  const skillMdFile = files.find(f => f.path === 'SKILL.md');
-  if (!skillMdFile) {
-    throw new Error(`SKILL.md not found in ${skillPath}`);
+  // 3. Parse SKILL.md frontmatter and discover references/scripts/assets paths
+  let snapshot: Omit<StorageSkillSnapshotType, 'tree'>;
+  try {
+    snapshot = parseSkillSnapshotFromFiles(files);
+  } catch (err) {
+    // Surface the skill path to make the error easier to debug
+    if (err instanceof Error && err.message.includes('SKILL.md not found')) {
+      throw new Error(`SKILL.md not found in ${skillPath}`);
+    }
+    throw err;
   }
 
-  const parsed = matter(skillMdFile.content as string);
-  const frontmatter = parsed.data;
-  const instructions = parsed.content.trim();
-
-  // 4. Discover references/, scripts/, assets/ subdirectories for the path arrays
-  const allPaths = files.map(f => f.path);
-  const references = collectSubdirPaths(allPaths, 'references');
-  const scripts = collectSubdirPaths(allPaths, 'scripts');
-  const assets = collectSubdirPaths(allPaths, 'assets');
-
-  // 5. Build snapshot
-  const snapshot: Omit<StorageSkillSnapshotType, 'tree'> = {
-    name: frontmatter.name,
-    description: frontmatter.description,
-    instructions,
-    license: frontmatter.license,
-    compatibility: frontmatter.compatibility,
-    metadata: frontmatter.metadata,
-    ...(references.length > 0 ? { references } : {}),
-    ...(scripts.length > 0 ? { scripts } : {}),
-    ...(assets.length > 0 ? { assets } : {}),
-  };
-
-  return { snapshot, tree, blobs };
+  return { snapshot, tree, blobs, files: fileNodes };
 }
 
 /**
diff --git a/packages/editor/src/namespaces/base.ts b/packages/editor/src/namespaces/base.ts
@@ -180,11 +180,11 @@ export abstract class CrudEditorNamespace<
    */
   clearCache(id?: string): void {
     if (id) {
-      const wasCached = this._cache.has(id);
       this._cache.delete(id);
-      if (wasCached) {
-        this.onCacheEvict(id);
-      }
+      // Always notify subclasses so they can clean up runtime registries
+      // (e.g. remove the agent from mastra.#agents), even if the entity
+      // wasn't in the editor cache (version-specific lookups skip caching).
+      this.onCacheEvict(id);
       this.logger?.debug(`[clearCache] Cleared cache for "${id}"`);
     } else {
       for (const cachedId of Array.from(this._cache.keys())) {
diff --git a/packages/editor/src/namespaces/skill.ts b/packages/editor/src/namespaces/skill.ts
@@ -68,13 +68,23 @@ export class EditorSkillNamespace extends CrudEditorNamespace<
       throw new Error('No blob store is configured. Register one via new MastraEditor({ blobStores: [...] })');
 
     // Collect and store blobs
-    const { snapshot, tree } = await publishSkillFromSource(source, skillPath, blobStore);
+    const { snapshot, tree, files } = await publishSkillFromSource(source, skillPath, blobStore);
 
-    // Update the skill with new version data + tree (creates a new version)
+    // Strip undefined keys before passing to update(); see the matching
+    // comment in the HTTP publish handler. Adapters that bind args raw
+    // (libsql, pg) reject undefined as an argument.
+    const snapshotUpdate: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(snapshot)) {
+      if (value !== undefined) snapshotUpdate[key] = value;
+    }
+
+    // Update the skill with new version data + tree + UI-facing file tree
+    // (creates a new version)
     await skillStore.update({
       id: skillId,
-      ...snapshot,
+      ...snapshotUpdate,
       tree,
+      files,
       status: 'published',
     });
 
diff --git a/packages/editor/src/namespaces/workspace.ts b/packages/editor/src/namespaces/workspace.ts
@@ -1,4 +1,4 @@
-import { Workspace } from '@mastra/core/workspace';
+import { Workspace, CompositeFilesystem } from '@mastra/core/workspace';
 import type { WorkspaceFilesystem, WorkspaceSandbox, SkillSource } from '@mastra/core/workspace';
 import type { WorkspaceConfig } from '@mastra/core/workspace';
 import type {
@@ -9,6 +9,7 @@ import type {
   StorageResolvedWorkspaceType,
   StorageListWorkspacesResolvedOutput,
   StorageWorkspaceSnapshotType,
+  StorageWorkspaceToolsConfig,
   StorageFilesystemConfig,
   StorageSandboxConfig,
 } from '@mastra/core/storage';
@@ -143,6 +144,71 @@ export class EditorWorkspaceNamespace extends CrudEditorNamespace<
     return new Workspace(config);
   }
 
+  /**
+   * Serialize a runtime Workspace instance into a StorageWorkspaceSnapshotType.
+   * The reverse of hydrateSnapshotToWorkspace — extracts provider IDs and config
+   * from live filesystem/sandbox instances so the workspace can be persisted to the DB.
+   */
+  async snapshotFromWorkspace(workspace: Workspace): Promise<StorageWorkspaceSnapshotType> {
+    const snapshot: StorageWorkspaceSnapshotType = {
+      name: workspace.name,
+    };
+
+    const fs = workspace.filesystem;
+    if (fs) {
+      if (fs instanceof CompositeFilesystem) {
+        // Workspace uses mounts — serialize each mounted filesystem
+        const mounts: Record<string, StorageFilesystemConfig> = {};
+        for (const [mountPath, mountedFs] of fs.mounts) {
+          mounts[mountPath] = await this.serializeFilesystem(mountedFs);
+        }
+        snapshot.mounts = mounts;
+      } else {
+        // Single filesystem
+        snapshot.filesystem = await this.serializeFilesystem(fs);
+      }
+    }
+
+    const sandbox = workspace.sandbox;
+    if (sandbox) {
+      // Sandbox.getInfo() is async and returns metadata that we round-trip through the
+      // stored config so resolveSandbox() can re-instantiate the provider with its
+      // original constructor configuration.
+      const info = typeof sandbox.getInfo === 'function' ? await sandbox.getInfo() : undefined;
+      snapshot.sandbox = {
+        provider: sandbox.provider,
+        config: info?.metadata ?? {},
+      };
+    }
+
+    const tools = workspace.getToolsConfig();
+    if (tools) {
+      // Only serialize static boolean values — runtime functions can't be stored
+      const storageTools: StorageWorkspaceToolsConfig = {};
+      if (typeof tools.enabled === 'boolean') storageTools.enabled = tools.enabled;
+      if (typeof tools.requireApproval === 'boolean') storageTools.requireApproval = tools.requireApproval;
+      if (Object.keys(storageTools).length > 0) {
+        snapshot.tools = storageTools;
+      }
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Serialize a runtime WorkspaceFilesystem into a StorageFilesystemConfig.
+   * Awaits getInfo() so async providers like CompositeFilesystem keep their mount metadata.
+   */
+  private async serializeFilesystem(fs: WorkspaceFilesystem): Promise<StorageFilesystemConfig> {
+    const info = typeof fs.getInfo === 'function' ? await fs.getInfo() : undefined;
+    const metadata = info && typeof info === 'object' && 'metadata' in info ? (info as any).metadata : undefined;
+    return {
+      provider: fs.provider,
+      config: metadata ?? {},
+      readOnly: fs.readOnly,
+    };
+  }
+
   /**
    * Resolve a stored filesystem config to a runtime WorkspaceFilesystem instance.
    * Looks up the provider by ID in the editor's registry (which includes built-in providers).
