@klhapp/skillmux 1.12.0 → 1.13.0

package/src/sync.ts

@@ -1,482 +0,0 @@
-import {
-  chmodSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readlinkSync,
-  readdirSync,
-  realpathSync,
-  renameSync,
-  rmSync,
-  symlinkSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { basename, join, relative } from "node:path";
-import { findSymlinks } from "./install";
-import { resolveSkillRoot } from "./vault";
-
-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;
-}
-
-function normalizeMarker(raw: Omit<SkillmuxMarker, "role"> & { role?: SkillmuxMarker["role"] }): SkillmuxMarker {
-  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 validateMarker(normalizeMarker(JSON.parse(readFileSync(newPath, "utf-8"))), newPath);
-  }
-  const legacyPath = join(dir, LEGACY_MARKER_FILENAME);
-  if (existsSync(legacyPath)) {
-    return validateMarker(normalizeMarker(JSON.parse(readFileSync(legacyPath, "utf-8"))), legacyPath);
-  }
-  return null;
-}
-
-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,
-    vault_path: vaultPath,
-    managed_entries: managedEntries,
-    created_at: createdAt,
-  };
-  const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
-  const serialized = JSON.stringify(marker, null, 2);
-  if (!existsSync(markerPath) || readFileSync(markerPath, "utf-8") !== serialized) {
-    writeFileAtomic(markerPath, serialized);
-  }
-}
-
-function writeFileAtomic(path: string, contents: string): void {
-  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    writeFileSync(temporaryPath, contents);
-    renameSync(temporaryPath, path);
-  } catch (error) {
-    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
-    throw error;
-  }
-}
-
-function replaceSymlinkAtomic(path: string, target: string): void {
-  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    symlinkSync(target, temporaryPath);
-    renameSync(temporaryPath, path);
-  } catch (error) {
-    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
-    throw error;
-  }
-}
-
-export function writeLocalVaultMarker(dir: string, vaultPath: string): void {
-  const marker: SkillmuxMarker = {
-    schema_version: 1,
-    managed_by: "skillmux",
-    role: "local_vault",
-    vault_path: vaultPath,
-    created_at: new Date().toISOString(),
-  };
-  writeFileSync(join(dir, SKILLMUX_MARKER_FILENAME), JSON.stringify(marker, null, 2));
-}
-
-export interface SyncTargetParams {
-  vaultPath: string;
-  targetDir: string;
-  targetName: string;
-  coreSkillIds: string[];
-  localVaultPaths?: string[];
-}
-
-export interface SyncTargetResult {
-  added: string[];
-  removed: string[];
-  /** Core skills whose directory contains an internal symlink and were refused —
-   *  syncTarget symlinks the whole skill directory into the target, so an internal
-   *  symlink would otherwise be exposed to the agent regardless of how it got into
-   *  the vault (install/update already reject them, but a shared git-backed vault
-   *  can still be tampered with directly). */
-  skipped: string[];
-}
-
-export interface SyncTargetOptions {
-  dryRun?: boolean;
-}
-
-/** Splits `skillIds` into those safe to symlink into a target and those refused
- *  for containing an internal symlink (see SyncTargetResult.skipped). */
-function partitionSyncable(
-  skillIds: string[],
-  skillSource: (skillId: string) => string,
-): { syncable: string[]; skipped: string[] } {
-  const syncable: string[] = [];
-  const skipped: string[] = [];
-  for (const skillId of skillIds) {
-    if (findSymlinks(join(skillSource(skillId), skillId)).length > 0) skipped.push(skillId);
-    else syncable.push(skillId);
-  }
-  return { syncable, skipped };
-}
-
-export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions = {}): SyncTargetResult {
-  const { vaultPath, targetDir, targetName, coreSkillIds, localVaultPaths = [] } = params;
-  const { dryRun = false } = options;
-  const skillSource = (skillId: string) => resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
-
-  if (!existsSync(targetDir)) {
-    const { syncable, skipped } = partitionSyncable(coreSkillIds, skillSource);
-    if (dryRun) return { added: syncable, removed: [], skipped };
-    mkdirSync(targetDir, { recursive: true });
-    for (const skillId of syncable) {
-      symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
-    }
-    writeTargetMarker(targetDir, targetName, vaultPath, syncable);
-    return { added: syncable, removed: [], skipped };
-  }
-
-  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 = [...managedEntries].filter((name) => existing.includes(name) && !desired.has(name));
-  const addedCandidates = coreSkillIds.filter((skillId) => !existing.includes(skillId));
-  const { syncable: added, skipped } = partitionSyncable(addedCandidates, skillSource);
-  if (dryRun) return { added, removed, skipped };
-
-  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.filter((skillId) => !skipped.includes(skillId)),
-    marker.created_at,
-  );
-
-  return { added, removed, skipped };
-}
-
-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}`,
-    );
-  }
-}
-
-export interface TargetMarkerRehomePlan {
-  dir: string;
-  markerPath: string;
-  marker: SkillmuxMarker;
-  links: TargetLinkRehomePlan[];
-}
-
-interface TargetLinkRehomePlan {
-  entryPath: string;
-  previousTarget: string;
-  nextTarget: string;
-}
-
-/**
- * Proves every managed entry resolves either to its active source or exactly to
- * the vault recorded in its marker. Only the latter links are re-pointed.
- */
-export function planTargetMarkerRehome(
-  dir: string,
-  targetName: string,
-  vaultPath: string,
-  localVaultPaths: string[] = [],
-): TargetMarkerRehomePlan {
-  const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
-  if (!existsSync(markerPath)) {
-    throw new Error(`${dir} has a legacy marker; rehome requires .skillmux ownership`);
-  }
-  const marker = readSkillmuxMarker(dir);
-  if (!marker) throw new Error(`${dir} is not owned by skillmux`);
-  if (marker.role !== "target") throw new Error(`${dir} has a local_vault marker, not target ownership`);
-  if (marker.schema_version !== 1) {
-    throw new Error(`${dir} has a legacy marker; rehome requires schema_version 1`);
-  }
-  if (marker.target !== targetName) {
-    throw new Error(`${dir} is owned by target "${marker.target}", not "${targetName}"`);
-  }
-
-  const links: TargetLinkRehomePlan[] = [];
-  for (const skillId of marker.managed_entries ?? []) {
-    if (basename(skillId) !== skillId) {
-      throw new Error(`${dir} marker has an invalid managed entry "${skillId}"`);
-    }
-    const entryPath = join(dir, skillId);
-    if (!lstatSync(entryPath).isSymbolicLink()) {
-      throw new Error(`${entryPath} is not the managed symlink recorded by ${dir}`);
-    }
-    const sourceRoot = resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
-    const expectedPath = join(sourceRoot, skillId);
-    if (!existsSync(expectedPath)) {
-      throw new Error(`${entryPath} cannot be proven to resolve from the configured vault's ${skillId}`);
-    }
-    const resolvedEntryPath = realpathSync(entryPath);
-    if (resolvedEntryPath === realpathSync(expectedPath)) continue;
-
-    const previousPath = join(marker.vault_path!, skillId);
-    if (!existsSync(previousPath) || resolvedEntryPath !== realpathSync(previousPath)) {
-      throw new Error(`${entryPath} does not resolve to the configured vault's ${skillId}`);
-    }
-    links.push({ entryPath, previousTarget: readlinkSync(entryPath), nextTarget: expectedPath });
-  }
-
-  return { dir, markerPath, marker, links };
-}
-
-/** Applies only preflighted rehome plans. All plans are validated before the first write. */
-export function applyTargetMarkerRehome(plans: TargetMarkerRehomePlan[], vaultPath: string): void {
-  const completedLinks: TargetLinkRehomePlan[] = [];
-  const completedMarkers: TargetMarkerRehomePlan[] = [];
-  try {
-    for (const plan of plans) {
-      for (const link of plan.links) {
-        replaceSymlinkAtomic(link.entryPath, link.nextTarget);
-        completedLinks.push(link);
-      }
-    }
-    for (const plan of plans) {
-      writeTargetMarker(
-        plan.dir,
-        plan.marker.target!,
-        vaultPath,
-        plan.marker.managed_entries ?? [],
-        plan.marker.created_at,
-      );
-      completedMarkers.push(plan);
-    }
-  } catch (error) {
-    for (const plan of completedMarkers.reverse()) {
-      writeFileAtomic(plan.markerPath, JSON.stringify(plan.marker, null, 2));
-    }
-    for (const link of completedLinks.reverse()) {
-      replaceSymlinkAtomic(link.entryPath, link.previousTarget);
-    }
-    throw error;
-  }
-}
-
-/**
- * Marks an existing directory as skillmux-owned without touching its content —
- * the consented, one-time adoption skillmux init performs (see SkillmuxMarker in
- * schema.json: "the only path allowed to create a .skillmux marker on a
- * 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, vaultPath: string): AdoptTargetResult {
-  preflightAdoptTarget(dir, targetName, vaultPath);
-  if (readSkillmuxMarker(dir)) return { adopted: false };
-  writeTargetMarker(dir, targetName, vaultPath, []);
-  return { adopted: true };
-}
-
-export interface RestoreMonolithResult {
-  restored: boolean;
-}
-
-export function restoreMonolith(targetDir: string, vaultPath: string): RestoreMonolithResult {
-  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, 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(path, rel);
-}
-
-export interface ProjectGroupInput {
-  paths: string[];
-  skills: string[];
-}
-
-export interface SyncProjectTargetsParams {
-  vaultPath: string;
-  targetDir: string;
-  targetName: string;
-  projectGroups: Record<string, ProjectGroupInput>;
-  localVaultPaths?: string[];
-}
-
-export interface ProjectPinSyncResult extends SyncTargetResult {
-  group: string;
-  path: string;
-  pinDir: string;
-}
-
-export function syncProjectTargets(
-  params: SyncProjectTargetsParams,
-  options: SyncTargetOptions = {},
-): ProjectPinSyncResult[] {
-  const { vaultPath, targetDir, targetName, projectGroups, localVaultPaths = [] } = params;
-  const results: ProjectPinSyncResult[] = [];
-
-  for (const [group, projectGroup] of Object.entries(projectGroups)) {
-    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, path, pinDir, ...result });
-    }
-  }
-
-  return results;
-}
-
-export const HOOK_MARKER = "# managed-by: skillmux sync --install-hook";
-export const LEGACY_HOOK_MARKER = "# managed-by: skr sync --install-hook";
-
-export interface InstallHookResult {
-  installed: boolean;
-}
-
-export function installPostMergeHook(vaultPath: string): InstallHookResult {
-  const hookPath = join(vaultPath, ".git", "hooks", "post-merge");
-
-  if (existsSync(hookPath)) {
-    const existing = readFileSync(hookPath, "utf-8");
-    if (existing.includes(HOOK_MARKER) || existing.includes(LEGACY_HOOK_MARKER)) return { installed: false };
-    throw new Error(`${hookPath} already exists and is not managed by skillmux — refusing to overwrite`);
-  }
-
-  const script = `#!/bin/sh\n${HOOK_MARKER}\nskillmux sync\n`;
-  writeFileSync(hookPath, script);
-  chmodSync(hookPath, 0o755);
-  return { installed: true };
-}

package/src/toml-writer.ts

@@ -1,51 +0,0 @@
-export function stringifyToml(obj: Record<string, any>): string {
-  let out = "";
-  const topLevel: Record<string, any> = {};
-  const sections: Record<string, any> = {};
-
-  for (const [k, v] of Object.entries(obj)) {
-    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
-      sections[k] = v;
-    } else {
-      topLevel[k] = v;
-    }
-  }
-
-  for (const [k, v] of Object.entries(topLevel)) {
-    out += `${k} = ${formatTomlVal(v)}\n`;
-  }
-  if (Object.keys(topLevel).length > 0) out += "\n";
-
-  for (const [secName, secObj] of Object.entries(sections)) {
-    out += stringifyTomlSection([secName], secObj);
-  }
-
-  return out;
-}
-
-export function stringifyTomlSection(path: string[], obj: Record<string, any>): string {
-  let out = `[${path.join(".")}]\n`;
-  const subSections: Record<string, any> = {};
-
-  for (const [k, v] of Object.entries(obj)) {
-    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
-      subSections[k] = v;
-    } else {
-      out += `${k} = ${formatTomlVal(v)}\n`;
-    }
-  }
-  out += "\n";
-
-  for (const [subName, subObj] of Object.entries(subSections)) {
-    out += stringifyTomlSection([...path, subName], subObj);
-  }
-
-  return out;
-}
-
-export function formatTomlVal(v: unknown): string {
-  if (typeof v === "string") return JSON.stringify(v);
-  if (typeof v === "boolean" || typeof v === "number") return String(v);
-  if (Array.isArray(v)) return JSON.stringify(v);
-  return JSON.stringify(v);
-}