@klhapp/skillmux 0.4.5 → 0.6.0

package/src/setup.ts

@@ -0,0 +1,145 @@
+import {
+  existsSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { SKILL_ID_PATTERN } from "./vault";
+
+export interface VaultHealth {
+  path: string;
+  state: "missing" | "broken-symlink" | "not-directory" | "empty" | "ready";
+  ok: boolean;
+  skillCount: number;
+  message: string;
+}
+
+export interface ConfigInitPlan {
+  configPath: string;
+  vaultPath: string;
+  action: "create" | "preserve";
+  content?: string;
+}
+
+export function inspectVault(path: string): VaultHealth {
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {
+        path,
+        state: "missing",
+        ok: false,
+        skillCount: 0,
+        message: `vault does not exist: ${path}`,
+      };
+    }
+    throw error;
+  }
+
+  if (stat.isSymbolicLink()) {
+    try {
+      realpathSync(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return {
+          path,
+          state: "broken-symlink",
+          ok: false,
+          skillCount: 0,
+          message: `vault is a dangling symlink: ${path}`,
+        };
+      }
+      throw error;
+    }
+  }
+
+  const resolvedStat = stat.isSymbolicLink() ? statSync(path) : stat;
+  if (!resolvedStat.isDirectory()) {
+    return {
+      path,
+      state: "not-directory",
+      ok: false,
+      skillCount: 0,
+      message: `vault is not a directory: ${path}`,
+    };
+  }
+
+  const skillCount = readdirSync(path, { withFileTypes: true }).filter(
+    (entry) =>
+      entry.isDirectory() &&
+      SKILL_ID_PATTERN.test(entry.name) &&
+      existsSync(join(path, entry.name, "SKILL.md")),
+  ).length;
+  if (skillCount === 0) {
+    return {
+      path,
+      state: "empty",
+      ok: false,
+      skillCount,
+      message: `vault contains no skill directories: ${path}`,
+    };
+  }
+
+  return {
+    path,
+    state: "ready",
+    ok: true,
+    skillCount,
+    message: `vault ready: ${path} (${skillCount} ${skillCount === 1 ? "skill" : "skills"})`,
+  };
+}
+
+export function planConfigInit(configPath: string, vaultPath: string): ConfigInitPlan {
+  if (existsSync(configPath)) {
+    return { configPath, vaultPath, action: "preserve" };
+  }
+
+  const vaultHealth = inspectVault(vaultPath);
+  if (!vaultHealth.ok) {
+    throw new Error(vaultHealth.message);
+  }
+
+  return {
+    configPath,
+    vaultPath,
+    action: "create",
+    content: `vault_path = ${JSON.stringify(vaultPath)}\n`,
+  };
+}
+
+export function applyConfigInit(plan: ConfigInitPlan): "created" | "preserved" {
+  if (plan.action === "preserve" || existsSync(plan.configPath)) {
+    return "preserved";
+  }
+
+  mkdirSync(dirname(plan.configPath), { recursive: true });
+  const temporaryPath = join(
+    dirname(plan.configPath),
+    `.${basename(plan.configPath)}.${process.pid}.${crypto.randomUUID()}.tmp`,
+  );
+  writeFileSync(temporaryPath, plan.content as string, { encoding: "utf8", mode: 0o600 });
+  try {
+    linkSync(temporaryPath, plan.configPath);
+    return "created";
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      return "preserved";
+    }
+    throw error;
+  } finally {
+    unlinkSync(temporaryPath);
+  }
+}
+
+export function rollbackConfigInit(plan: ConfigInitPlan): void {
+  if (plan.action === "create") rmSync(plan.configPath, { force: true });
+}

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,9 +216,31 @@ 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 };