Obsidian Upgrade MigrationSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: obsidian-upgrade-migration
description: 'Migrate Obsidian plugins between API versions and handle breaking changes.

  Use when upgrading to new Obsidian versions, handling API deprecations,

  or migrating plugin code to new patterns.

  Trigger with phrases like "obsidian upgrade", "obsidian migration",

  "obsidian API changes", "update obsidian plugin".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- obsidian
- api
- migration
compatibility: Designed for Claude Code
---
# Obsidian Upgrade Migration

## Current State

!`npm list 2>/dev/null | head -20`
!`cat manifest.json 2>/dev/null || echo 'No manifest.json in cwd'`

## Overview

Upgrade an Obsidian plugin between versions: migrate persisted settings with version checks, replace deprecated API calls, update `manifest.json` `minAppVersion`, and test across Obsidian releases.

## Prerequisites

- Existing Obsidian plugin with source code
- Current `manifest.json` and `versions.json`
- Access to [Obsidian changelog](https://obsidian.md/changelog) and [breaking changes docs](https://docs.obsidian.md/Plugins/Releasing/Breaking+changes)
- Node.js 18+ with npm or pnpm

## Instructions

### Step 1: Audit Current Version Compatibility

Check what your plugin currently targets and what the user's Obsidian version requires:

```bash
# Current plugin target
echo "=== manifest.json ==="
cat manifest.json | python3 -c "
import json, sys
m = json.load(sys.stdin)
print(f\"Plugin: {m['id']} v{m['version']}\")
print(f\"minAppVersion: {m['minAppVersion']}\")
"

# Current obsidian type definitions
echo "=== obsidian package version ==="
npm ls obsidian 2>/dev/null || echo "Not found in node_modules"

# Check versions.json for version history
echo "=== versions.json ==="
cat versions.json 2>/dev/null | python3 -m json.tool || echo "No versions.json"
```

### Step 2: Update the Obsidian Type Definitions

```bash
# Update to latest obsidian types
npm install obsidian@latest --save-dev

# Check what changed
npm diff obsidian 2>/dev/null | head -100
```

Then check for TypeScript errors against the new types:

```bash
npx tsc --noEmit 2>&1 | head -50
```

Every error here is a breaking change you need to address.

### Step 3: Settings Migration with Version Tracking

Implement a version-aware `loadData()` pattern so existing users' settings survive upgrades:

```typescript
interface PluginSettings {
  _version: number; // Internal schema version
  // v1 fields
  enabled: boolean;
  // v2 fields (added in plugin v2.0.0)
  syncInterval: number;
  // v3 fields (added in plugin v3.0.0)
  theme: 'light' | 'dark' | 'system';
}

const CURRENT_SETTINGS_VERSION = 3;

const DEFAULT_SETTINGS: PluginSettings = {
  _version: CURRENT_SETTINGS_VERSION,
  enabled: true,
  syncInterval: 300,
  theme: 'system',
};

async loadSettings(): Promise<PluginSettings> {
  const raw = await this.loadData();
  if (!raw) return { ...DEFAULT_SETTINGS };

  const version = raw._version ?? 1;
  let settings = { ...raw };

  // v1 -> v2: add syncInterval
  if (version < 2) {
    settings.syncInterval = DEFAULT_SETTINGS.syncInterval;
    console.log('[your-plugin] Migrated settings v1 -> v2');
  }

  // v2 -> v3: add theme, rename old field
  if (version < 3) {
    settings.theme = DEFAULT_SETTINGS.theme;
    // Rename deprecated field
    if ('darkMode' in settings) {
      settings.theme = settings.darkMode ? 'dark' : 'light';
      delete settings.darkMode;
    }
    console.log('[your-plugin] Migrated settings v2 -> v3');
  }

  settings._version = CURRENT_SETTINGS_VERSION;
  await this.saveData(settings); // Persist the migration
  return settings as PluginSettings;
}
```

### Step 4: Replace Deprecated API Calls

Common deprecations and their replacements:

**Vault API changes:**

```typescript
// DEPRECATED: vault.modify with string path
await this.app.vault.modify(filePath, content);
// REPLACEMENT: use TFile object
const file = this.app.vault.getAbstractFileByPath(filePath);
if (file instanceof TFile) {
  await this.app.vault.modify(file, content);
}

// DEPRECATED: vault.create returns void in older versions
this.app.vault.create(path, content);
// REPLACEMENT: returns TFile, handle it
const newFile = await this.app.vault.create(path, content);
```

**Event registration changes:**

```typescript
// DEPRECATED: workspace.on('file-open') with old signature
this.app.workspace.on('file-open', (file) => { ... });
// REPLACEMENT: use registerEvent for proper cleanup
this.registerEvent(
  this.app.workspace.on('file-open', (file) => { ... })
);
```

**Editor API (CodeMirror 5 to 6 migration):**

```typescript
// DEPRECATED: accessing CM5 editor instance
const cm = (editor as any).cm;
cm.getValue(); // CM5

// REPLACEMENT: use Obsidian's Editor interface
const content = editor.getValue();
const cursor = editor.getCursor();
editor.replaceRange(text, cursor);

// For CM6-specific features, use EditorView extension:
import { EditorView, ViewPlugin } from '@codemirror/view';

this.registerEditorExtension(
  ViewPlugin.fromClass(class {
    constructor(view: EditorView) {
      // CM6 view access
    }
  })
);
```

**FileManager changes:**

```typescript
// DEPRECATED: processFrontMatter sync signature
this.app.fileManager.processFrontMatter(file, (fm) => {
  fm.tags = ['updated'];
});
// REPLACEMENT: async signature (Obsidian 1.4+)
await this.app.fileManager.processFrontMatter(file, (fm) => {
  fm.tags = ['updated'];
});
```

### Step 5: Update manifest.json

Bump `minAppVersion` to the lowest Obsidian version that supports all APIs you use:

```json
{
  "id": "your-plugin",
  "name": "Your Plugin",
  "version": "3.0.0",
  "minAppVersion": "1.5.0",
  "description": "...",
  "author": "...",
  "isDesktopOnly": false
}
```

Update `versions.json` to map your plugin version to the minimum Obsidian version:

```json
{
  "1.0.0": "0.15.0",
  "2.0.0": "1.0.0",
  "3.0.0": "1.5.0"
}
```

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.