initial public release.

src/core/project-upgrader/KGProjectUpgrader.ts

@@ -0,0 +1,34 @@
+import { KGProject } from '../KGProject';
+import { upgradeToV1 } from './upgradeToV1';
+
+/**
+ * Upgrade the given project to the latest structure version, one version at a time.
+ * This function is safe to call multiple times; it will no-op if up-to-date.
+ */
+export function upgradeProjectToLatest(project: KGProject): KGProject {
+  if (!project) return project;
+
+  const currentVersion = project.getProjectStructureVersion?.() ?? 0;
+  const targetVersion = KGProject.CURRENT_PROJECT_STRUCTURE_VERSION;
+
+  if (currentVersion >= targetVersion) {
+    return project;
+  }
+
+  let workingProject: KGProject = project;
+
+  for (let nextVersion = currentVersion + 1; nextVersion <= targetVersion; nextVersion++) {
+    switch (nextVersion) {
+      case 1: {
+        workingProject = upgradeToV1(workingProject);
+        break;
+      }
+      default: {
+        // If an upgrader is missing, throw to prevent loading incompatible structures
+        throw new Error(`No upgrader found for project structure version ${nextVersion}`);
+      }
+    }
+  }
+
+  return workingProject;
+}

src/core/project-upgrader/upgradeToV1.ts

@@ -0,0 +1,41 @@
+import { KGProject } from '../KGProject';
+import { KGTrack } from '../track/KGTrack';
+import { KGMidiTrack, type InstrumentType } from '../track/KGMidiTrack';
+
+/**
+ * Upgrade a project from structure version 0 to 1.
+ * Keep logic minimal for now; future migrations should extend this.
+ */
+export function upgradeToV1(project: KGProject): KGProject {
+  try {
+    const tracks: KGTrack[] = project.getTracks();
+
+    const legacyToNewInstrumentMap: Record<string, InstrumentType> = {
+      PIANO: 'acoustic_grand_piano',
+      GUITAR: 'acoustic_guitar_nylon',
+      BASS: 'electric_bass_finger',
+      DRUMS: 'standard',
+    } as const;
+
+    const isMidiTrack = (track: KGTrack): track is KGMidiTrack => {
+      return track.getCurrentType() === 'KGMidiTrack';
+    };
+
+    tracks.forEach(track => {
+      if (!isMidiTrack(track)) return;
+
+      const currentInstrument = (track as KGMidiTrack).getInstrument() as unknown as string;
+      const mapped = legacyToNewInstrumentMap[currentInstrument];
+      if (mapped) {
+        (track as KGMidiTrack).setInstrument(mapped);
+      }
+    });
+  } finally {
+    // Always set the project structure version to 1 to mark migration complete
+    project.setProjectStructureVersion(1);
+  }
+
+  return project;
+}
+
+