@klhapp/skillmux 0.4.4 → 0.5.0

package/src/init.ts

@@ -1,7 +1,33 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { serializeManifest, type Manifest, MANIFEST_FILENAME } from "./manifest";
-import { adoptTarget, readSkillmuxMarker } from "./sync";
+import {
+  parseManifest,
+  resolveManifestPath,
+  serializeManifest,
+  type Manifest,
+  CORE_SKILL_LIMIT,
+  MANIFEST_FILENAME,
+} from "./manifest";
+import {
+  adoptTarget,
+  preflightAdoptTarget,
+  readSkillmuxMarker,
+  SKILLMUX_MARKER_FILENAME,
+} from "./sync";
 import { SKILL_ID_PATTERN } from "./vault";
 
 export const DEFAULT_SURFACE_CANDIDATES = ["~/.claude/skills", "~/.agents/skills"];
@@ -20,10 +46,13 @@ export function surfaceCandidates(): string[] {
 
 export interface SurfaceCandidate {
   path: string;
+  canonicalPath?: string;
   exists: boolean;
   isSymlink: boolean;
   skillCount: number;
   alreadyMarked: boolean;
+  state: "missing" | "directory" | "broken-symlink" | "external-symlink" | "full-vault" | "unsupported";
+  deliveryMode: "managed-pins" | "full-vault" | "external";
 }
 
 function countSkillDirs(dir: string): number {
@@ -36,17 +65,93 @@ function countSkillDirs(dir: string): number {
   return count;
 }
 
-export function detectSurfaces(candidatePaths: string[]): SurfaceCandidate[] {
-  return candidatePaths.map((path) => {
-    if (!existsSync(path)) {
-      return { path, exists: false, isSymlink: false, skillCount: 0, alreadyMarked: false };
+export function detectSurfaces(candidatePaths: string[], vaultPath?: string): SurfaceCandidate[] {
+  const canonicalVaultPath = vaultPath ? realpathSync(vaultPath) : undefined;
+
+  return candidatePaths.map((path): SurfaceCandidate => {
+    let stat;
+    try {
+      stat = lstatSync(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      return {
+        path,
+        exists: false,
+        isSymlink: false,
+        skillCount: 0,
+        alreadyMarked: false,
+        state: "missing",
+        deliveryMode: "managed-pins",
+      };
     }
+
+    if (stat.isSymbolicLink()) {
+      let canonicalPath: string;
+      try {
+        canonicalPath = realpathSync(path);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        return {
+          path,
+          exists: false,
+          isSymlink: true,
+          skillCount: 0,
+          alreadyMarked: false,
+          state: "broken-symlink",
+          deliveryMode: "external",
+        };
+      }
+
+      const isFullVault = canonicalVaultPath !== undefined && canonicalPath === canonicalVaultPath;
+      return {
+        path,
+        canonicalPath,
+        exists: true,
+        isSymlink: true,
+        skillCount: 0,
+        alreadyMarked: false,
+        state: isFullVault ? "full-vault" : "external-symlink",
+        deliveryMode: isFullVault ? "full-vault" : "external",
+      };
+    }
+
+    const canonicalPath = realpathSync(path);
+    const isFullVault = canonicalVaultPath !== undefined && canonicalPath === canonicalVaultPath;
+    if (isFullVault) {
+      return {
+        path,
+        canonicalPath,
+        exists: true,
+        isSymlink: false,
+        skillCount: 0,
+        alreadyMarked: false,
+        state: "full-vault",
+        deliveryMode: "full-vault",
+      };
+    }
+
+    if (!stat.isDirectory()) {
+      return {
+        path,
+        canonicalPath,
+        exists: true,
+        isSymlink: false,
+        skillCount: 0,
+        alreadyMarked: false,
+        state: "unsupported",
+        deliveryMode: "external",
+      };
+    }
+
     return {
       path,
+      canonicalPath,
       exists: true,
-      isSymlink: lstatSync(path).isSymbolicLink(),
+      isSymlink: false,
       skillCount: countSkillDirs(path),
       alreadyMarked: readSkillmuxMarker(path) !== null,
+      state: "directory",
+      deliveryMode: "managed-pins",
     };
   });
 }
@@ -68,6 +173,45 @@ export function deriveTargetName(path: string): string {
 export interface ConfirmedTarget {
   name: string;
   dir: string;
+  migrateFullVault?: boolean;
+}
+
+export interface InitTransactionParticipant {
+  apply: () => void;
+  rollback: () => void;
+}
+
+function preflightManagedTargets(vaultPath: string, targets: ConfirmedTarget[]): void {
+  const canonicalVaultPath = realpathSync(vaultPath);
+
+  for (const target of targets) {
+    let stat;
+    try {
+      stat = lstatSync(target.dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+
+    if (stat.isSymbolicLink()) {
+      const canonicalTargetPath = realpathSync(target.dir);
+      if (target.migrateFullVault && canonicalTargetPath === canonicalVaultPath) {
+        continue;
+      }
+      throw new Error(
+        `target "${target.name}" (${target.dir}) is a symbolic link; classify or migrate it before managed-pins adoption`,
+      );
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`target "${target.name}" (${target.dir}) is not a directory`);
+    }
+    if (realpathSync(target.dir) === canonicalVaultPath) {
+      throw new Error(
+        `target "${target.name}" (${target.dir}) is the full-vault surface; it cannot be adopted as managed-pins`,
+      );
+    }
+    preflightAdoptTarget(target.dir, target.name, vaultPath);
+  }
 }
 
 /**
@@ -76,19 +220,138 @@ export interface ConfirmedTarget {
  * first if it doesn't exist yet). Unconfirmed candidates are simply never
  * passed in — this function never discovers paths on its own.
  */
-export function applyInit(vaultPath: string, confirmedTargets: ConfirmedTarget[]): Manifest {
+export function planInitManifest(
+  vaultPath: string,
+  confirmedTargets: ConfirmedTarget[],
+  coreSkillIds: string[] = [],
+): Manifest {
+  preflightManagedTargets(vaultPath, confirmedTargets);
+
+  const existingManifestPath = resolveManifestPath(vaultPath);
+  const existingManifest = existingManifestPath
+    ? parseManifest(readFileSync(existingManifestPath, "utf-8"))
+    : { ...proposeManifest([]), targets: {} };
   const manifest: Manifest = {
-    ...proposeManifest([]),
-    targets: Object.fromEntries(
-      confirmedTargets.map((target) => [target.name, { dir: target.dir, project_groups: [] }]),
-    ),
+    ...existingManifest,
+    core: {
+      ...existingManifest.core,
+      skills: [...new Set([...existingManifest.core.skills, ...coreSkillIds])],
+    },
+    targets: {
+      ...existingManifest.targets,
+      ...Object.fromEntries(
+        confirmedTargets.map((target) => {
+          const existingTarget = existingManifest.targets[target.name];
+          return [
+            target.name,
+            existingTarget
+              ? { ...existingTarget, dir: target.dir }
+              : { dir: target.dir, host: hostname(), project_groups: [] },
+          ];
+        }),
+      ),
+    },
   };
+  if (manifest.core.skills.length > CORE_SKILL_LIMIT) {
+    throw new Error(
+      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${CORE_SKILL_LIMIT}`,
+    );
+  }
+  for (const skillId of coreSkillIds) {
+    if (!SKILL_ID_PATTERN.test(skillId) || !existsSync(join(vaultPath, skillId, "SKILL.md"))) {
+      throw new Error(`[core] skill "${skillId}" does not exist in the vault`);
+    }
+    for (const [groupName, group] of Object.entries(existingManifest.project ?? {})) {
+      if (group.skills.includes(skillId)) {
+        throw new Error(`skill "${skillId}" appears in both [core] and [project.${groupName}]`);
+      }
+    }
+  }
+  return manifest;
+}
+
+export function applyInit(
+  vaultPath: string,
+  confirmedTargets: ConfirmedTarget[],
+  participant?: InitTransactionParticipant,
+  coreSkillIds: string[] = [],
+): Manifest {
+  const manifest = planInitManifest(vaultPath, confirmedTargets, coreSkillIds);
+
+  const manifestPath = join(vaultPath, MANIFEST_FILENAME);
+  const serializedManifest = serializeManifest(manifest);
+  const shouldWriteManifest =
+    !existsSync(manifestPath) || readFileSync(manifestPath, "utf-8") !== serializedManifest;
+  const createdDirs: string[] = [];
+  const adoptedDirs: string[] = [];
+  const migratedFullVaultDirs: Array<{ dir: string; linkTarget: string }> = [];
+  let participantApplied = false;
+
+  try {
+    for (const target of confirmedTargets) {
+      let targetStat;
+      try {
+        targetStat = lstatSync(target.dir);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      if (targetStat?.isSymbolicLink()) {
+        if (!target.migrateFullVault || realpathSync(target.dir) !== realpathSync(vaultPath)) {
+          throw new Error(
+            `target "${target.name}" (${target.dir}) changed to an unsafe symbolic link after preflight`,
+          );
+        }
+        const linkTarget = readlinkSync(target.dir);
+        unlinkSync(target.dir);
+        mkdirSync(target.dir, { recursive: true });
+        migratedFullVaultDirs.push({ dir: target.dir, linkTarget });
+      } else if (targetStat && !targetStat.isDirectory()) {
+        throw new Error(`target "${target.name}" (${target.dir}) changed to a non-directory after preflight`);
+      }
+      if (!existsSync(target.dir)) {
+        mkdirSync(target.dir, { recursive: true });
+        createdDirs.push(target.dir);
+      }
+      if (adoptTarget(target.dir, target.name, vaultPath).adopted) {
+        adoptedDirs.push(target.dir);
+      }
+    }
 
-  writeFileSync(join(vaultPath, MANIFEST_FILENAME), serializeManifest(manifest));
+    if (participant) {
+      participant.apply();
+      participantApplied = true;
+    }
 
-  for (const target of confirmedTargets) {
-    if (!existsSync(target.dir)) mkdirSync(target.dir, { recursive: true });
-    adoptTarget(target.dir, target.name);
+    if (shouldWriteManifest) {
+      const temporaryManifestPath = join(
+        vaultPath,
+        `.${MANIFEST_FILENAME}.${process.pid}-${Date.now()}.tmp`,
+      );
+      try {
+        writeFileSync(temporaryManifestPath, serializedManifest);
+        renameSync(temporaryManifestPath, manifestPath);
+      } catch (error) {
+        if (existsSync(temporaryManifestPath)) unlinkSync(temporaryManifestPath);
+        throw error;
+      }
+    }
+  } catch (error) {
+    try {
+      if (participantApplied) participant?.rollback();
+    } finally {
+      for (const dir of adoptedDirs.reverse()) {
+        const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
+        if (existsSync(markerPath)) unlinkSync(markerPath);
+      }
+      for (const migration of migratedFullVaultDirs.reverse()) {
+        if (existsSync(migration.dir)) rmdirSync(migration.dir);
+        symlinkSync(migration.linkTarget, migration.dir);
+      }
+      for (const dir of createdDirs.reverse()) {
+        if (existsSync(dir)) rmdirSync(dir);
+      }
+    }
+    throw error;
   }
 
   return manifest;

package/src/manifest.ts

@@ -19,12 +19,13 @@ const groupNameSchema = z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64);
 const skillIdSchema = z.string().regex(SKILL_ID_PATTERN);
 
 const projectGroupSchema = z.object({
-  repos: z.array(z.string().min(1)),
+  paths: z.array(z.string().min(1)),
   skills: z.array(skillIdSchema),
 }).strict();
 
 const targetSchema = z.object({
   dir: z.string().min(1),
+  host: z.string().min(1).optional(),
   project_groups: z.array(groupNameSchema).default([]),
 }).strict();
 
@@ -54,6 +55,15 @@ export function parseManifest(toml: string): Manifest {
             `[targets.${String(issue.path[1])}] uses the removed field "project" (boolean) — replace it with "project_groups" (an array of [project.<group>] names).`,
           );
         }
+        if (
+          issue.code === "unrecognized_keys" &&
+          issue.path[0] === "project" &&
+          issue.keys.includes("repos")
+        ) {
+          throw new Error(
+            `[project.${String(issue.path[1])}] uses the removed field "repos" — replace it with "paths".`,
+          );
+        }
       }
     }
     throw error;
@@ -70,13 +80,14 @@ export function serializeManifest(manifest: Manifest): string {
 
   for (const [name, group] of Object.entries(manifest.project ?? {})) {
     sections.push(
-      `[project.${name}]\nrepos = ${tomlStringArray(group.repos)}\nskills = ${tomlStringArray(group.skills)}`,
+      `[project.${name}]\npaths = ${tomlStringArray(group.paths)}\nskills = ${tomlStringArray(group.skills)}`,
     );
   }
 
   for (const [name, target] of Object.entries(manifest.targets)) {
+    const host = target.host ? `\nhost = ${JSON.stringify(target.host)}` : "";
     sections.push(
-      `[targets.${name}]\ndir = ${JSON.stringify(target.dir)}\nproject_groups = ${tomlStringArray(target.project_groups)}`,
+      `[targets.${name}]\ndir = ${JSON.stringify(target.dir)}${host}\nproject_groups = ${tomlStringArray(target.project_groups)}`,
     );
   }
 
@@ -106,15 +117,15 @@ export function unpinCore(manifest: Manifest, skillId: string): Manifest {
   return { ...manifest, core: { skills: manifest.core.skills.filter((id) => id !== skillId) } };
 }
 
-export function pinProject(manifest: Manifest, skillId: string, group: string, repos?: string[]): Manifest {
+export function pinProject(manifest: Manifest, skillId: string, group: string, paths?: string[]): Manifest {
   if (!groupNameSchema.safeParse(group).success) {
     throw new Error(`invalid group name "${group}" — must match /^[a-z][a-z0-9_-]*$/ (max 64 chars)`);
   }
   const existingGroup = manifest.project?.[group];
 
   if (!existingGroup) {
-    if (!repos || repos.length === 0) {
-      throw new Error(`group "${group}" does not exist — pass --repo <path> at least once to create it`);
+    if (!paths || paths.length === 0) {
+      throw new Error(`group "${group}" does not exist — pass --path <path> at least once to create it`);
     }
     const existing = findExistingPin(manifest, skillId);
     if (existing) {
@@ -122,12 +133,12 @@ export function pinProject(manifest: Manifest, skillId: string, group: string, r
     }
     return {
       ...manifest,
-      project: { ...manifest.project, [group]: { repos, skills: [skillId] } },
+      project: { ...manifest.project, [group]: { paths, skills: [skillId] } },
     };
   }
 
-  if (repos && repos.length > 0) {
-    throw new Error(`group "${group}" already exists — --repo is only used when creating a new group`);
+  if (paths && paths.length > 0) {
+    throw new Error(`group "${group}" already exists — --path is only used when creating a new group`);
   }
   const existing = findExistingPin(manifest, skillId);
   if (existing) {
@@ -160,7 +171,7 @@ export interface ManifestValidationResult {
   notes: string[];
 }
 
-const CORE_SKILL_LIMIT = 25;
+export const CORE_SKILL_LIMIT = 25;
 
 function requireCoreVaultRoot(skillId: string, vaultPath: string, localVaultPaths: string[], location: string): void {
   const root = resolveSkillRoot(skillId, vaultPath, localVaultPaths);
@@ -208,9 +219,9 @@ export function validateManifest(
         throw new Error(`skill "${skillId}" appears in both [core] and [project.${groupName}]`);
       }
     }
-    for (const repo of group.repos) {
-      if (!existsSync(expandHome(repo))) {
-        notes.push(`[project.${groupName}] repos path not found locally, skipped: ${repo}`);
+    for (const path of group.paths) {
+      if (!existsSync(expandHome(path))) {
+        notes.push(`[project.${groupName}] paths entry not found locally, skipped: ${path}`);
       }
     }
   }

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 });
+}