@klhapp/skillmux 0.4.5 → 0.6.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

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { expandHome } from "./config";
@@ -25,13 +25,14 @@ const projectGroupSchema = z.object({
 
 const targetSchema = z.object({
   dir: z.string().min(1),
+  host: z.string().min(1).optional(),
   project_groups: z.array(groupNameSchema).default([]),
 }).strict();
 
 const manifestSchema = z.object({
   core: z.object({ skills: z.array(skillIdSchema) }).strict(),
   project: z.record(groupNameSchema, projectGroupSchema).optional(),
-  targets: z.record(groupNameSchema, targetSchema),
+  targets: z.record(groupNameSchema, targetSchema).default({}),
 }).strict();
 
 export type ProjectGroup = z.infer<typeof projectGroupSchema>;
@@ -84,14 +85,25 @@ export function serializeManifest(manifest: Manifest): string {
   }
 
   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)}`,
     );
   }
 
   return `${sections.join("\n\n")}\n`;
 }
 
+export function writeManifestAtomic(path: string, manifest: Manifest): void {
+  const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, serializeManifest(manifest), "utf8");
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}
+
 function findExistingPin(manifest: Manifest, skillId: string): string | null {
   if (manifest.core.skills.includes(skillId)) return "[core]";
   for (const [groupName, group] of Object.entries(manifest.project ?? {})) {
@@ -165,11 +177,100 @@ export function unpinProject(manifest: Manifest, skillId: string, group: string)
   };
 }
 
+export interface UpsertProjectOptions {
+  name: string;
+  paths: string[];
+  skills: string[];
+  targets: string[];
+}
+
+export function upsertProject(manifest: Manifest, options: UpsertProjectOptions): Manifest {
+  if (!groupNameSchema.safeParse(options.name).success) {
+    throw new Error(
+      `invalid group name "${options.name}" — must match /^[a-z][a-z0-9_-]*$/ (max 64 chars)`,
+    );
+  }
+
+  const existingGroup = manifest.project?.[options.name] ?? { paths: [], skills: [] };
+  for (const skillId of options.skills) {
+    if (!skillIdSchema.safeParse(skillId).success) {
+      throw new Error(`invalid skill ID "${skillId}"`);
+    }
+    if (existingGroup.skills.includes(skillId)) continue;
+    const existing = findExistingPin(manifest, skillId);
+    if (existing) throw new Error(`skill "${skillId}" already pinned in ${existing}`);
+  }
+
+  const targets = { ...manifest.targets };
+  for (const targetName of options.targets) {
+    const target = targets[targetName];
+    if (!target) throw new Error(`target "${targetName}" does not exist`);
+    targets[targetName] = {
+      ...target,
+      project_groups: [...new Set([...target.project_groups, options.name])],
+    };
+  }
+
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [options.name]: {
+        paths: [...new Set([...existingGroup.paths, ...options.paths])],
+        skills: [...new Set([...existingGroup.skills, ...options.skills])],
+      },
+    },
+    targets,
+  };
+}
+
+export function updateProjectPaths(
+  manifest: Manifest,
+  group: string,
+  changes: { add?: string[]; remove?: string[] },
+): Manifest {
+  const existingGroup = manifest.project?.[group];
+  if (!existingGroup) throw new Error(`[project.${group}] does not exist`);
+  const removed = new Set(changes.remove ?? []);
+  const paths = [...new Set([...existingGroup.paths, ...(changes.add ?? [])])]
+    .filter((path) => !removed.has(path));
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [group]: { ...existingGroup, paths },
+    },
+  };
+}
+
+export function updateProjectTargets(
+  manifest: Manifest,
+  group: string,
+  changes: { attach?: string[]; detach?: string[] },
+): Manifest {
+  if (!manifest.project?.[group]) throw new Error(`[project.${group}] does not exist`);
+  const attach = new Set(changes.attach ?? []);
+  const detach = new Set(changes.detach ?? []);
+  const requested = new Set([...attach, ...detach]);
+  for (const target of requested) {
+    if (!manifest.targets[target]) throw new Error(`target "${target}" does not exist`);
+  }
+  return {
+    ...manifest,
+    targets: Object.fromEntries(Object.entries(manifest.targets).map(([name, target]) => {
+      let groups = target.project_groups;
+      if (attach.has(name)) groups = [...new Set([...groups, group])];
+      if (detach.has(name)) groups = groups.filter((item) => item !== group);
+      return [name, { ...target, project_groups: groups }];
+    })),
+  };
+}
+
 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);

package/src/output.ts

@@ -110,12 +110,11 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   return bestMatch;
 }
 
-export function isInteractive(): boolean {
-  return (
-    process.stdout.isTTY === true &&
-    !process.env.NO_COLOR &&
-    process.env.TERM !== "dumb"
-  );
+export function isInteractive(
+  env: NodeJS.ProcessEnv = process.env,
+  stdoutIsTTY = process.stdout.isTTY,
+): boolean {
+  return stdoutIsTTY === true && env.TERM !== "dumb";
 }
 
 export function renderTargetBanner(target: ResolvedTarget): void {

package/src/project-setup.ts

@@ -0,0 +1,36 @@
+import { resolve } from "node:path";
+
+interface ResolveProjectDirectoryOptions {
+  cwd?: string;
+  findGitRoot?: (cwd: string) => string | null;
+}
+
+function findGitRoot(cwd: string): string | null {
+  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return null;
+  const root = result.stdout.toString().trim();
+  return root || null;
+}
+
+export function resolveProjectDirectory(
+  explicitPath?: string,
+  options: ResolveProjectDirectoryOptions = {},
+): string {
+  const cwd = options.cwd ?? process.cwd();
+  if (explicitPath) return resolve(explicitPath);
+  const gitRoot = (options.findGitRoot ?? findGitRoot)(cwd);
+  return resolve(gitRoot ?? cwd);
+}
+
+export function suggestProjectName(directoryName: string): string {
+  const slug = directoryName
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const prefixed = /^[a-z]/.test(slug) ? slug : `project-${slug || "workspace"}`;
+  return prefixed.slice(0, 64).replace(/-+$/g, "");
+}

package/src/prompts.ts

@@ -0,0 +1,69 @@
+import { createInterface } from "node:readline/promises";
+
+export interface SelectOption<T extends string> {
+  value: T;
+  label: string;
+  detail?: string;
+  selected?: boolean;
+}
+
+export function parseNumberSelection(input: string, optionCount: number): number[] {
+  if (input.trim() === "") return [];
+  const indexes = input.split(",").map((part) => {
+    const choice = Number(part.trim());
+    if (!Number.isInteger(choice) || choice < 1 || choice > optionCount) {
+      throw new Error(`select numbers between 1 and ${optionCount}, separated by commas`);
+    }
+    return choice - 1;
+  });
+  return [...new Set(indexes)].sort((a, b) => a - b);
+}
+
+export function parseCommaList(input: string): string[] {
+  return [...new Set(input.split(",").map((value) => value.trim()).filter(Boolean))];
+}
+
+export function shouldUseWizard(
+  args: readonly string[],
+  mode: { interactive: boolean; json: boolean; dryRun: boolean },
+): boolean {
+  if (!mode.interactive || mode.json || mode.dryRun || args.includes("--yes")) return false;
+  if (args.includes("--interactive")) return true;
+  return args.length === 0;
+}
+
+export async function promptMultiSelect<T extends string>(
+  question: string,
+  options: readonly SelectOption<T>[],
+): Promise<T[]> {
+  console.log(`\n${question}`);
+  options.forEach((option, index) => {
+    const checked = option.selected ? "x" : " ";
+    const detail = option.detail ? `  ${option.detail}` : "";
+    console.log(`  ${index + 1}. [${checked}] ${option.label}${detail}`);
+  });
+  const defaults = options
+    .map((option, index) => option.selected ? String(index + 1) : "")
+    .filter(Boolean)
+    .join(",");
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaults ? ` [${defaults}]` : "";
+    const answer = await readline.question(`Select numbers, comma-separated${suffix}: `);
+    const selection = answer.trim() === "" && defaults ? defaults : answer;
+    return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
+  } finally {
+    readline.close();
+  }
+}
+
+export async function promptText(question: string, defaultValue = ""): Promise<string> {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    const answer = (await readline.question(`${question}${suffix}: `)).trim();
+    return answer || defaultValue;
+  } finally {
+    readline.close();
+  }
+}