@klhapp/skillmux 0.4.4 → 0.5.0

package/src/sync.ts

@@ -7,10 +7,12 @@ export const SKILLMUX_MARKER_FILENAME = ".skillmux";
 export const LEGACY_MARKER_FILENAME = ".skr";
 
 export interface SkillmuxMarker {
+  schema_version?: 1;
   managed_by: "skillmux" | "skr";
   role: "target" | "local_vault";
   target?: string;
   vault_path?: string;
+  managed_entries?: string[];
   created_at: string;
 }
 
@@ -18,30 +20,68 @@ function normalizeMarker(raw: Omit<SkillmuxMarker, "role"> & { role?: SkillmuxMa
   return { ...raw, role: raw.role ?? "target" };
 }
 
+function validateMarker(marker: SkillmuxMarker, path: string): SkillmuxMarker {
+  if (marker.schema_version === undefined) return marker;
+  if (marker.schema_version !== 1) throw new Error(`${path}: unsupported marker schema_version`);
+  if (marker.managed_by !== "skillmux") throw new Error(`${path}: invalid managed_by`);
+  if (marker.role !== "target" && marker.role !== "local_vault") {
+    throw new Error(`${path}: invalid role`);
+  }
+  if (marker.role === "target") {
+    if (typeof marker.target !== "string" || marker.target.length === 0) {
+      throw new Error(`${path}: target marker is missing target`);
+    }
+    if (typeof marker.vault_path !== "string" || marker.vault_path.length === 0) {
+      throw new Error(`${path}: target marker is missing vault_path`);
+    }
+    if (!Array.isArray(marker.managed_entries) || marker.managed_entries.some((entry) => typeof entry !== "string")) {
+      throw new Error(`${path}: target marker is missing managed_entries`);
+    }
+  } else if (typeof marker.vault_path !== "string" || marker.vault_path.length === 0) {
+    throw new Error(`${path}: local_vault marker is missing vault_path`);
+  }
+  if (typeof marker.created_at !== "string") throw new Error(`${path}: marker is missing created_at`);
+  return marker;
+}
+
 export function readSkillmuxMarker(dir: string): SkillmuxMarker | null {
   const newPath = join(dir, SKILLMUX_MARKER_FILENAME);
   if (existsSync(newPath)) {
-    return normalizeMarker(JSON.parse(readFileSync(newPath, "utf-8")));
+    return validateMarker(normalizeMarker(JSON.parse(readFileSync(newPath, "utf-8"))), newPath);
   }
   const legacyPath = join(dir, LEGACY_MARKER_FILENAME);
   if (existsSync(legacyPath)) {
-    return normalizeMarker(JSON.parse(readFileSync(legacyPath, "utf-8")));
+    return validateMarker(normalizeMarker(JSON.parse(readFileSync(legacyPath, "utf-8"))), legacyPath);
   }
   return null;
 }
 
-function writeSkillmuxMarker(dir: string, targetName: string): void {
+function writeTargetMarker(
+  dir: string,
+  targetName: string,
+  vaultPath: string,
+  managedEntries: string[],
+  createdAt = new Date().toISOString(),
+): void {
   const marker: SkillmuxMarker = {
+    schema_version: 1,
     managed_by: "skillmux",
     role: "target",
     target: targetName,
-    created_at: new Date().toISOString(),
+    vault_path: vaultPath,
+    managed_entries: managedEntries,
+    created_at: createdAt,
   };
-  writeFileSync(join(dir, SKILLMUX_MARKER_FILENAME), JSON.stringify(marker, null, 2));
+  const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
+  const serialized = JSON.stringify(marker, null, 2);
+  if (!existsSync(markerPath) || readFileSync(markerPath, "utf-8") !== serialized) {
+    writeFileSync(markerPath, serialized);
+  }
 }
 
 export function writeLocalVaultMarker(dir: string, vaultPath: string): void {
   const marker: SkillmuxMarker = {
+    schema_version: 1,
     managed_by: "skillmux",
     role: "local_vault",
     vault_path: vaultPath,
@@ -78,23 +118,61 @@ export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions
     for (const skillId of coreSkillIds) {
       symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
     }
-    writeSkillmuxMarker(targetDir, targetName);
+    writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds);
     return { added: [...coreSkillIds], removed: [] };
   }
 
-  if (!readSkillmuxMarker(targetDir)) {
+  let marker = readSkillmuxMarker(targetDir);
+  if (!marker) {
     throw new Error(`not owned by skillmux — run skillmux init`);
   }
+  if (marker.role === "local_vault") {
+    throw new Error(`${targetDir} has a local_vault marker, not target ownership`);
+  }
+  if (marker.target !== targetName) {
+    throw new Error(`${targetDir} is owned by target "${marker.target}", not "${targetName}"`);
+  }
+  if (marker.schema_version === undefined) {
+    const legacyEntries = readdirSync(targetDir).filter(
+      (name) => name !== SKILLMUX_MARKER_FILENAME && name !== LEGACY_MARKER_FILENAME,
+    );
+    if (legacyEntries.length > 0) {
+      throw new Error(
+        `${targetDir} has a legacy marker with untracked entries; remove or migrate them before running skillmux sync`,
+      );
+    }
+    marker = {
+      schema_version: 1,
+      managed_by: "skillmux",
+      role: "target",
+      target: targetName,
+      vault_path: vaultPath,
+      managed_entries: [],
+      created_at: marker.created_at,
+    };
+    if (!dryRun) writeTargetMarker(targetDir, targetName, vaultPath, [], marker.created_at);
+  }
+  if (marker.vault_path !== vaultPath) {
+    throw new Error(
+      `${targetDir} marker recorded vault_path ${marker.vault_path}, currently configured vault_path is ${vaultPath}`,
+    );
+  }
 
   const desired = new Set(coreSkillIds);
   const existing = readdirSync(targetDir).filter((name) => name !== SKILLMUX_MARKER_FILENAME && name !== LEGACY_MARKER_FILENAME);
+  const managedEntries = new Set(marker.managed_entries ?? []);
+  const collisions = coreSkillIds.filter((skillId) => existing.includes(skillId) && !managedEntries.has(skillId));
+  if (collisions.length > 0) {
+    throw new Error(`unmanaged entry collisions in ${targetDir}: ${collisions.join(", ")}`);
+  }
 
-  const removed = existing.filter((name) => !desired.has(name));
+  const removed = [...managedEntries].filter((name) => existing.includes(name) && !desired.has(name));
   const added = coreSkillIds.filter((skillId) => !existing.includes(skillId));
   if (dryRun) return { added, removed };
 
   for (const name of removed) unlinkSync(join(targetDir, name));
   for (const skillId of added) symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
+  writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds, marker.created_at);
 
   return { added, removed };
 }
@@ -103,6 +181,22 @@ export interface AdoptTargetResult {
   adopted: boolean;
 }
 
+export function preflightAdoptTarget(dir: string, targetName: string, vaultPath: string): void {
+  const marker = readSkillmuxMarker(dir);
+  if (marker?.role === "local_vault") {
+    throw new Error(`${dir} has a local_vault marker, not target ownership`);
+  }
+  if (!marker) return;
+  if (marker.target !== targetName) {
+    throw new Error(`${dir} is already owned by target "${marker.target}", not "${targetName}"`);
+  }
+  if (marker.schema_version !== undefined && marker.vault_path !== vaultPath) {
+    throw new Error(
+      `${dir} marker recorded vault_path ${marker.vault_path}, currently configured vault_path is ${vaultPath}`,
+    );
+  }
+}
+
 /**
  * Marks an existing directory as skillmux-owned without touching its content —
  * the consented, one-time adoption skillmux init performs (see SkillmuxMarker in
@@ -110,9 +204,10 @@ export interface AdoptTargetResult {
  * previously-unmarked directory"). syncTarget's fresh-dir case handles the
  * "doesn't exist yet" side of that rule; this handles "already exists".
  */
-export function adoptTarget(dir: string, targetName: string): AdoptTargetResult {
+export function adoptTarget(dir: string, targetName: string, vaultPath: string): AdoptTargetResult {
+  preflightAdoptTarget(dir, targetName, vaultPath);
   if (readSkillmuxMarker(dir)) return { adopted: false };
-  writeSkillmuxMarker(dir, targetName);
+  writeTargetMarker(dir, targetName, vaultPath, []);
   return { adopted: true };
 }
 
@@ -121,26 +216,48 @@ export interface RestoreMonolithResult {
 }
 
 export function restoreMonolith(targetDir: string, vaultPath: string): RestoreMonolithResult {
-  if (!readSkillmuxMarker(targetDir)) {
+  const marker = readSkillmuxMarker(targetDir);
+  if (!marker) {
     return { restored: false };
   }
+  if (marker.role === "local_vault") {
+    throw new Error(`${targetDir} has a local_vault marker, not target ownership`);
+  }
+  if (marker.schema_version === undefined) {
+    throw new Error(`${targetDir} has a legacy marker; migrate it before restoring full-vault delivery`);
+  }
+  if (marker.vault_path !== vaultPath) {
+    throw new Error(
+      `${targetDir} marker recorded vault_path ${marker.vault_path}, currently configured vault_path is ${vaultPath}`,
+    );
+  }
+  const managedEntries = new Set(marker.managed_entries ?? []);
+  const unmanagedEntries = readdirSync(targetDir).filter(
+    (name) =>
+      name !== SKILLMUX_MARKER_FILENAME &&
+      name !== LEGACY_MARKER_FILENAME &&
+      !managedEntries.has(name),
+  );
+  if (unmanagedEntries.length > 0) {
+    throw new Error(`refusing to restore over unmanaged entries in ${targetDir}: ${unmanagedEntries.join(", ")}`);
+  }
   rmSync(targetDir, { recursive: true, force: true });
   symlinkSync(vaultPath, targetDir);
   return { restored: true };
 }
 
-export function resolveProjectPinDir(targetDir: string, repo: string): string {
+export function resolveProjectPinDir(targetDir: string, path: string): string {
   const rel = relative(homedir(), targetDir);
   if (rel === "" || rel.startsWith("..")) {
     throw new Error(
       `target dir "${targetDir}" must be inside $HOME to compute a project pin dir (got relative path "${rel}")`,
     );
   }
-  return join(repo, rel);
+  return join(path, rel);
 }
 
 export interface ProjectGroupInput {
-  repos: string[];
+  paths: string[];
   skills: string[];
 }
 
@@ -154,7 +271,7 @@ export interface SyncProjectTargetsParams {
 
 export interface ProjectPinSyncResult extends SyncTargetResult {
   group: string;
-  repo: string;
+  path: string;
   pinDir: string;
 }
 
@@ -166,14 +283,14 @@ export function syncProjectTargets(
   const results: ProjectPinSyncResult[] = [];
 
   for (const [group, projectGroup] of Object.entries(projectGroups)) {
-    for (const repo of projectGroup.repos) {
-      if (!existsSync(repo)) continue;
-      const pinDir = resolveProjectPinDir(targetDir, repo);
+    for (const path of projectGroup.paths) {
+      if (!existsSync(path)) continue;
+      const pinDir = resolveProjectPinDir(targetDir, path);
       const result = syncTarget(
         { vaultPath, targetDir: pinDir, targetName, coreSkillIds: projectGroup.skills, localVaultPaths },
         options,
       );
-      results.push({ group, repo, pinDir, ...result });
+      results.push({ group, path, pinDir, ...result });
     }
   }