Skip to content

armgit / chops

Public Imported from GitHub
0

Your AI agent skills, finally organized. A macOS app to browse, edit, and manage skills across Claude Code, Cursor, Codex, Windsurf, and Amp.

fix: add SwiftData schema versioning to prevent silent data loss (#87)

Josh Pigford4698e045fc64
diff --git a/CLAUDE.md b/CLAUDE.md
index 767930d..e28cfba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,12 +38,15 @@ No test suite exists. Validate manually by building and running.
## Architecture
**Entry:** `Chops/App/ChopsApp.swift` → sets up SwiftData ModelContainer + Sparkle updater.
+SwiftData store path is explicit: `~/Library/Application Support/Chops/Chops.store`. Do not rely on the implicit `default.store`.
**State:** `AppState` is an `@Observable` singleton holding UI filters, search text, and selection state.
**Models (SwiftData):**
- `Skill` — a discovered skill file. Uniquely identified by resolved symlink path. Tracks which tools it's installed in.
-- `SkillCollection` — user-created groupings of skills.
+- `SkillCollection` — user-created groupings of skills (pure user data, not filesystem-backed — data loss is permanent).
+
+**Schema versioning:** SwiftData models use `VersionedSchema` + `SchemaMigrationPlan` (see `SchemaVersions.swift`). Each schema version must declare its own nested `@Model` snapshots; app code reaches the current version through top-level `typealias`es like `Skill = SchemaV1.Skill`. When adding or changing a stored property, freeze the previous schema in place, add a new schema version (e.g. `SchemaV2`) with its own nested models, move the typealiases to the new version, and add the corresponding `MigrationStage`. Never point an older schema version at live top-level models — future migrations will crash with duplicate checksums.
**Services:**
- `SkillScanner` — probes tool directories (~/.claude/skills/, ~/.cursor/rules/, etc.), parses frontmatter, upserts into SwiftData. Deduplicates via resolved symlink paths.
diff --git a/Chops.xcodeproj/project.pbxproj b/Chops.xcodeproj/project.pbxproj
index 799f970..4d3d45b 100644
--- a/Chops.xcodeproj/project.pbxproj
+++ b/Chops.xcodeproj/project.pbxproj
@@ -50,6 +50,7 @@
B5B95B9DA63A734F25470FF5 /* SchemaVersions.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1F8AA042D5D8A9F92F35CA3 /* SchemaVersions.swift */; };
BD584933CCE2B650345C4CF1 /* ToolSource.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5487D9027B97F7E9EE9A1F4A /* ToolSource.swift */; };
BFF9964529E6C48F4F7BCB97 /* MarkdownSyntaxHighlighter.swift in Sources */ = {isa = PBXBuildFile; fileRef = 135976FA0E8358E099157DE1 /* MarkdownSyntaxHighlighter.swift */; };
+ C2A028F40A1C665D29495DB6 /* StoreBootstrap.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3D23D43EC788E51ED1C265FE /* StoreBootstrap.swift */; };
C30BEAE03E54BD36F257A925 /* ToolFilterView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9A5774429CCE83C2AFBE046C /* ToolFilterView.swift */; };
C6CFF37CC0B155E8846344A4 /* ChopsIcon.icon in Resources */ = {isa = PBXBuildFile; fileRef = 04C3C644B72DD508A7CBC403 /* ChopsIcon.icon */; };
C983C685C6296C2EF73CE57D /* CursorACPAgent.swift in Sources */ = {isa = PBXBuildFile; fileRef = 07899C351E63B32277272A59 /* CursorACPAgent.swift */; };
@@ -89,6 +90,7 @@
3314080A44DEB895223E36D5 /* RemoteServer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RemoteServer.swift; sourceTree = "<group>"; };
372FA72F2C179B79470DF86A /* MarkdownRenderer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MarkdownRenderer.swift; sourceTree = "<group>"; };
3A4F680B33C74A38FCF5ADD5 /* MDCParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MDCParser.swift; sourceTree = "<group>"; };
+ 3D23D43EC788E51ED1C265FE /* StoreBootstrap.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StoreBootstrap.swift; sourceTree = "<group>"; };
4CA102A49ACFB23BC15794F8 /* CollectionListView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CollectionListView.swift; sourceTree = "<group>"; };
511C5A2149EFF77BDA7D4692 /* ACPLogger.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ACPLogger.swift; sourceTree = "<group>"; };
5155D141EF812A3FE9ADF59C /* SkillParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SkillParser.swift; sourceTree = "<group>"; };
@@ -248,6 +250,7 @@
9FC9D3E83D8640CC258CF361 /* SkillRegistry.swift */,
E6A5B26D335C1AFB6CDE8207 /* SkillScanner.swift */,
6797D4AC1970DB9ACB5ACA73 /* SSHService.swift */,
+ 3D23D43EC788E51ED1C265FE /* StoreBootstrap.swift */,
12C5CD1627D4EFF58AEF4F71 /* TemplateManager.swift */,
3B8985D8816557B264BF0AD8 /* ACP */,
);
@@ -448,6 +451,7 @@
E6F4E1CF50F2F78F5BA9BAC9 /* SkillPreviewView.swift in Sources */,
846B58F3B105D1734DC6FA75 /* SkillRegistry.swift in Sources */,
6A8E0927D95BB14C9F377F4E /* SkillScanner.swift in Sources */,
+ C2A028F40A1C665D29495DB6 /* StoreBootstrap.swift in Sources */,
3F0ED402E77D8D25C600BAED /* TemplateManager.swift in Sources */,
038F5975DA97A3211EF4D448 /* ThinkingView.swift in Sources */,
53C393C13E30EC439317509F /* ToolBadge.swift in Sources */,
diff --git a/Chops/App/ChopsApp.swift b/Chops/App/ChopsApp.swift
index 3cad963..4e58128 100644
--- a/Chops/App/ChopsApp.swift
+++ b/Chops/App/ChopsApp.swift
@@ -17,11 +17,15 @@ struct ChopsApp: App {
}
var sharedModelContainer: ModelContainer = {
- let schema = Schema([Skill.self, SkillCollection.self, RemoteServer.self])
- let config = ModelConfiguration(schema: schema, isStoredInMemoryOnly: false)
+ let schema = Schema(versionedSchema: SchemaV1.self)
do {
- return try ModelContainer(for: schema, configurations: [config])
+ let config = try StoreBootstrap.makeConfiguration(schema: schema)
+ return try ModelContainer(
+ for: schema,
+ migrationPlan: ChopsMigrationPlan.self,
+ configurations: [config]
+ )
} catch {
fatalError("Could not create ModelContainer: \(error)")
}
diff --git a/Chops/Models/Collection.swift b/Chops/Models/Collection.swift
index a9f5fa0..bb65ba0 100644
--- a/Chops/Models/Collection.swift
+++ b/Chops/Models/Collection.swift
@@ -1,19 +1,3 @@
-import SwiftData
import Foundation
-@Model
-final class SkillCollection {
- @Attribute(.unique) var name: String
- var icon: String
- var sortOrder: Int
-
- @Relationship(inverse: \Skill.collections)
- var skills: [Skill]
-
- init(name: String, icon: String = "folder", skills: [Skill] = [], sortOrder: Int = 0) {
- self.name = name
- self.icon = icon
- self.skills = skills
- self.sortOrder = sortOrder
- }
-}
+// SkillCollection is declared inside SchemaV1 so each schema version owns its snapshot.
diff --git a/Chops/Models/RemoteServer.swift b/Chops/Models/RemoteServer.swift
index 64eb231..d554aa0 100644
--- a/Chops/Models/RemoteServer.swift
+++ b/Chops/Models/RemoteServer.swift
@@ -1,37 +1,6 @@
-import SwiftData
import Foundation
-@Model
-final class RemoteServer {
- @Attribute(.unique) var id: String
- var label: String
- var host: String
- var port: Int
- var username: String
- var skillsBasePath: String
- var sshKeyPath: String?
- var lastSyncDate: Date?
- var lastSyncError: String?
-
- @Relationship(deleteRule: .cascade, inverse: \Skill.remoteServer)
- var skills: [Skill]
-
- init(
- label: String,
- host: String,
- port: Int = 22,
- username: String,
- skillsBasePath: String
- ) {
- self.id = UUID().uuidString
- self.label = label
- self.host = host
- self.port = port
- self.username = username
- self.skillsBasePath = skillsBasePath
- self.skills = []
- }
-
+extension RemoteServer {
var sshDestination: String {
"\(username)@\(host)"
}
diff --git a/Chops/Models/SchemaVersions.swift b/Chops/Models/SchemaVersions.swift
index c850448..393933f 100644
--- a/Chops/Models/SchemaVersions.swift
+++ b/Chops/Models/SchemaVersions.swift
@@ -1,5 +1,131 @@
-import SwiftData
import Foundation
+import SwiftData
+
+enum SchemaV1: VersionedSchema {
+ static var versionIdentifier = Schema.Version(1, 0, 0)
+
+ static var models: [any PersistentModel.Type] {
+ [Skill.self, SkillCollection.self, RemoteServer.self]
+ }
+
+ @Model
+ final class Skill {
+ @Attribute(.unique) var resolvedPath: String
+ var filePath: String
+ var isDirectory: Bool
+ var name: String
+ var skillDescription: String
+ var content: String
+ var frontmatterData: Data?
+
+ var collections: [SkillCollection]
+ var isFavorite: Bool
+ var lastOpened: Date?
+ var fileModifiedDate: Date
+ var fileSize: Int
+ var isGlobal: Bool
+
+ var remoteServer: RemoteServer?
+ var remotePath: String?
+
+ var toolSourcesRaw: String
+ var installedPathsData: Data?
+ var kind: String = ItemKind.skill.rawValue
+
+ init(
+ filePath: String,
+ toolSource: ToolSource,
+ isDirectory: Bool = false,
+ name: String = "",
+ skillDescription: String = "",
+ content: String = "",
+ frontmatter: [String: String] = [:],
+ collections: [SkillCollection] = [],
+ isFavorite: Bool = false,
+ lastOpened: Date? = nil,
+ fileModifiedDate: Date = .now,
+ fileSize: Int = 0,
+ isGlobal: Bool = true,
+ resolvedPath: String = "",
+ kind: ItemKind = .skill
+ ) {
+ self.resolvedPath = resolvedPath.isEmpty ? filePath : resolvedPath
+ self.filePath = filePath
+ self.toolSourcesRaw = toolSource.rawValue
+ self.installedPathsData = try? JSONEncoder().encode([filePath])
+ self.isDirectory = isDirectory
+ self.name = name
+ self.skillDescription = skillDescription
+ self.content = content
+ self.frontmatterData = try? JSONEncoder().encode(frontmatter)
+ self.collections = collections
+ self.isFavorite = isFavorite
+ self.lastOpened = lastOpened
+ self.fileModifiedDate = fileModifiedDate
+ self.fileSize = fileSize
+ self.isGlobal = isGlobal
+ self.kind = kind.rawValue
+ }
+ }
+
+ @Model
+ final class SkillCollection {
+ @Attribute(.unique) var name: String
+ var icon: String
+ var sortOrder: Int
+
+ @Relationship(inverse: \Skill.collections)
+ var skills: [Skill]
+
+ init(name: String, icon: String = "folder", skills: [Skill] = [], sortOrder: Int = 0) {
+ self.name = name
+ self.icon = icon
+ self.skills = skills
+ self.sortOrder = sortOrder
+ }
+ }
+
+ @Model
+ final class RemoteServer {
+ @Attribute(.unique) var id: String
+ var label: String
+ var host: String
+ var port: Int
+ var username: String
+ var skillsBasePath: String
+ var sshKeyPath: String?
+ var lastSyncDate: Date?
+ var lastSyncError: String?
+
+ @Relationship(deleteRule: .cascade, inverse: \Skill.remoteServer)
+ var skills: [Skill]
+
+ init(
+ label: String,
+ host: String,
+ port: Int = 22,
+ username: String,
+ skillsBasePath: String
+ ) {
+ self.id = UUID().uuidString
+ self.label = label
+ self.host = host
+ self.port = port
+ self.username = username
+ self.skillsBasePath = skillsBasePath
+ self.skills = []
+ }
+ }
+}
+
+typealias Skill = SchemaV1.Skill
+typealias SkillCollection = SchemaV1.SkillCollection
+typealias RemoteServer = SchemaV1.RemoteServer
+
+enum ChopsMigrationPlan: SchemaMigrationPlan {
+ static var schemas: [any VersionedSchema.Type] {
+ [SchemaV1.self]
+ }
-// No versioned schema needed — SwiftData handles additive changes
-// (new optional properties + new entities) via automatic lightweight migration.
+ static var stages: [MigrationStage] { [] }
+}
diff --git a/Chops/Models/Skill.swift b/Chops/Models/Skill.swift
index 6f6d70d..e783779 100644
--- a/Chops/Models/Skill.swift
+++ b/Chops/Models/Skill.swift
@@ -31,26 +31,7 @@ enum ItemKind: String, Codable, CaseIterable {
}
}
-@Model
-final class Skill {
- @Attribute(.unique) var resolvedPath: String
- var filePath: String
- var isDirectory: Bool
- var name: String
- var skillDescription: String
- var content: String
- var frontmatterData: Data?
-
- var collections: [SkillCollection]
- var isFavorite: Bool
- var lastOpened: Date?
- var fileModifiedDate: Date
- var fileSize: Int
- var isGlobal: Bool
-
- var remoteServer: RemoteServer?
- var remotePath: String?
-
+extension Skill {
var isRemote: Bool { remoteServer != nil }
var isPlugin: Bool {
@@ -63,15 +44,6 @@ final class Skill {
isPlugin || isBundledOpenClawSkill
}
- /// Comma-separated tool raw values (e.g. "claude,cursor,codex")
- var toolSourcesRaw: String
-
- /// All file paths where this skill is installed (JSON-encoded array)
- var installedPathsData: Data?
-
- /// Raw `ItemKind` value. Defaults to `"skill"` for lightweight migration compatibility.
- var kind: String = ItemKind.skill.rawValue
-
// MARK: - Computed
var itemKind: ItemKind {
@@ -154,45 +126,6 @@ final class Skill {
return nil
}
- // MARK: - Init
-
- init(
- filePath: String,
- toolSource: ToolSource,
- isDirectory: Bool = false,
- name: String = "",
- skillDescription: String = "",
- content: String = "",
- frontmatter: [String: String] = [:],
-
- collections: [SkillCollection] = [],
- isFavorite: Bool = false,
- lastOpened: Date? = nil,
- fileModifiedDate: Date = .now,
- fileSize: Int = 0,
- isGlobal: Bool = true,
- resolvedPath: String = "",
- kind: ItemKind = .skill
- ) {
- self.resolvedPath = resolvedPath.isEmpty ? filePath : resolvedPath
- self.filePath = filePath
- self.toolSourcesRaw = toolSource.rawValue
- self.installedPathsData = try? JSONEncoder().encode([filePath]) // [String] encode never throws
- self.isDirectory = isDirectory
- self.name = name
- self.skillDescription = skillDescription
- self.content = content
- self.frontmatterData = try? JSONEncoder().encode(frontmatter) // [String: String] encode never throws
-
- self.collections = collections
- self.isFavorite = isFavorite
- self.lastOpened = lastOpened
- self.fileModifiedDate = fileModifiedDate
- self.fileSize = fileSize
- self.isGlobal = isGlobal
- self.kind = kind.rawValue
- }
-
// MARK: - Merge
/// Merge another location/tool into this skill
diff --git a/Chops/Services/StoreBootstrap.swift b/Chops/Services/StoreBootstrap.swift
new file mode 100644
index 0000000..7147dd3
--- /dev/null
+++ b/Chops/Services/StoreBootstrap.swift
@@ -0,0 +1,156 @@
+import Foundation
+import SwiftData
+
+enum StoreBootstrap {
+ static func makeConfiguration(schema: Schema) throws -> ModelConfiguration {
+ let storeURL = try prepareStoreURL(schema: schema)
+ return ModelConfiguration(schema: schema, url: storeURL)
+ }
+
+ private static func prepareStoreURL(schema: Schema) throws -> URL {
+ let fm = FileManager.default
+ let appSupportURL = try appSupportDirectory(using: fm)
+ let storeURL = appSupportURL.appendingPathComponent("Chops.store")
+
+ if !fm.fileExists(atPath: storeURL.path) {
+ try? removeStoreFiles(at: storeURL)
+ let legacyURL = try legacyStoreURL(using: fm)
+ if fm.fileExists(atPath: legacyURL.path) {
+ try migrateLegacyStore(from: legacyURL, to: storeURL, schema: schema)
+ }
+ }
+
+ return storeURL
+ }
+
+ private static func appSupportDirectory(using fm: FileManager) throws -> URL {
+ guard let baseURL = fm.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else {
+ throw CocoaError(.fileNoSuchFile)
+ }
+
+ let appSupportURL = baseURL.appendingPathComponent("Chops", isDirectory: true)
+ try fm.createDirectory(at: appSupportURL, withIntermediateDirectories: true)
+ return appSupportURL
+ }
+
+ private static func legacyStoreURL(using fm: FileManager) throws -> URL {
+ guard let baseURL = fm.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else {
+ throw CocoaError(.fileNoSuchFile)
+ }
+
+ return baseURL.appendingPathComponent("default.store")
+ }
+
+ private static func migrateLegacyStore(from legacyURL: URL, to storeURL: URL, schema: Schema) throws {
+ let legacyConfig = ModelConfiguration(schema: schema, url: legacyURL)
+ let storeConfig = ModelConfiguration(schema: schema, url: storeURL)
+
+ do {
+ let legacyContainer = try ModelContainer(
+ for: schema,
+ migrationPlan: ChopsMigrationPlan.self,
+ configurations: [legacyConfig]
+ )
+ let legacyContext = ModelContext(legacyContainer)
+
+ let storeContainer = try ModelContainer(
+ for: schema,
+ migrationPlan: ChopsMigrationPlan.self,
+ configurations: [storeConfig]
+ )
+ let storeContext = ModelContext(storeContainer)
+
+ try copyRemoteServers(from: legacyContext, to: storeContext)
+ try copyCollections(from: legacyContext, to: storeContext)
+ try copySkills(from: legacyContext, to: storeContext)
+ try storeContext.save()
+ } catch {
+ try? removeStoreFiles(at: storeURL)
+ throw error
+ }
+ }
+
+ private static func copyRemoteServers(from legacyContext: ModelContext, to storeContext: ModelContext) throws {
+ let descriptor = FetchDescriptor<RemoteServer>()
+ for legacyServer in try legacyContext.fetch(descriptor) {
+ let server = RemoteServer(
+ label: legacyServer.label,
+ host: legacyServer.host,
+ port: legacyServer.port,
+ username: legacyServer.username,
+ skillsBasePath: legacyServer.skillsBasePath
+ )
+ server.id = legacyServer.id
+ server.sshKeyPath = legacyServer.sshKeyPath
+ server.lastSyncDate = legacyServer.lastSyncDate
+ server.lastSyncError = legacyServer.lastSyncError
+ storeContext.insert(server)
+ }
+
+ try storeContext.save()
+ }
+
+ private static func copyCollections(from legacyContext: ModelContext, to storeContext: ModelContext) throws {
+ let descriptor = FetchDescriptor<SkillCollection>()
+ for legacyCollection in try legacyContext.fetch(descriptor) {
+ let collection = SkillCollection(
+ name: legacyCollection.name,
+ icon: legacyCollection.icon,
+ sortOrder: legacyCollection.sortOrder
+ )
+ storeContext.insert(collection)
+ }
+
+ try storeContext.save()
+ }
+
+ private static func copySkills(from legacyContext: ModelContext, to storeContext: ModelContext) throws {
+ let remoteServers = try storeContext.fetch(FetchDescriptor<RemoteServer>())
+ let collections = try storeContext.fetch(FetchDescriptor<SkillCollection>())
+
+ let serversByID = Dictionary(uniqueKeysWithValues: remoteServers.map { ($0.id, $0) })
+ let collectionsByName = Dictionary(uniqueKeysWithValues: collections.map { ($0.name, $0) })
+
+ let descriptor = FetchDescriptor<Skill>()
+ for legacySkill in try legacyContext.fetch(descriptor) {
+ let skill = Skill(
+ filePath: legacySkill.filePath,
+ toolSource: legacySkill.toolSource,
+ isDirectory: legacySkill.isDirectory,
+ name: legacySkill.name,
+ skillDescription: legacySkill.skillDescription,
+ content: legacySkill.content,
+ frontmatter: legacySkill.frontmatter,
+ isFavorite: legacySkill.isFavorite,
+ lastOpened: legacySkill.lastOpened,
+ fileModifiedDate: legacySkill.fileModifiedDate,
+ fileSize: legacySkill.fileSize,
+ isGlobal: legacySkill.isGlobal,
+ resolvedPath: legacySkill.resolvedPath,
+ kind: legacySkill.itemKind
+ )
+
+ skill.frontmatterData = legacySkill.frontmatterData
+ skill.toolSourcesRaw = legacySkill.toolSourcesRaw
+ skill.installedPathsData = legacySkill.installedPathsData
+ skill.remotePath = legacySkill.remotePath
+ skill.remoteServer = legacySkill.remoteServer.flatMap { serversByID[$0.id] }
+ skill.collections = legacySkill.collections.compactMap { collectionsByName[$0.name] }
+
+ storeContext.insert(skill)
+ }
+ }
+
+ private static func removeStoreFiles(at storeURL: URL) throws {
+ let fm = FileManager.default
+ let siblingURLs = [storeURL, sidecarURL(for: storeURL, suffix: "-shm"), sidecarURL(for: storeURL, suffix: "-wal")]
+
+ for url in siblingURLs where fm.fileExists(atPath: url.path) {
+ try fm.removeItem(at: url)
+ }
+ }
+
+ private static func sidecarURL(for storeURL: URL, suffix: String) -> URL {
+ URL(fileURLWithPath: storeURL.path + suffix)
+ }
+}