@klhapp/skillmux 1.12.0 → 1.13.0

package/src/init-instructions.ts

@@ -1,192 +0,0 @@
-import {
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-import { DISCOVERY_PARAGRAPH } from "./init";
-import { getAgentDefinition, type AgentId } from "./init-agents";
-
-export const INSTRUCTION_BLOCK_START = "<!-- skillmux:discovery:start -->";
-export const INSTRUCTION_BLOCK_END = "<!-- skillmux:discovery:end -->";
-
-const MANAGED_BLOCK = [
-  INSTRUCTION_BLOCK_START,
-  DISCOVERY_PARAGRAPH,
-  INSTRUCTION_BLOCK_END,
-].join("\n");
-
-export interface InstructionChange {
-  path: string;
-  agents: AgentId[];
-  status: "create" | "update" | "unchanged";
-  before: string | null;
-  after: string;
-}
-
-export interface InstructionPlan {
-  changes: InstructionChange[];
-  manual: Array<{ agent: AgentId; reason: string }>;
-}
-
-interface InstructionPlanOptions {
-  home?: string;
-  codexHome?: string;
-  claudeConfigDir?: string;
-  readFile?: (path: string) => string | null;
-}
-
-function instructionPath(
-  agent: AgentId,
-  options: Required<Pick<InstructionPlanOptions, "home" | "codexHome" | "claudeConfigDir">>,
-): string | undefined {
-  return getAgentDefinition(agent).instructions?.global?.(options);
-}
-
-function readInstructionFile(path: string): string | null {
-  try {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink()) {
-      throw new Error(`instruction file is a symbolic link and will not be modified: ${path}`);
-    }
-    if (!stat.isFile()) throw new Error(`instruction path is not a file: ${path}`);
-    return readFileSync(path, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw error;
-  }
-}
-
-function withManagedBlock(existing: string | null, path: string): string {
-  if (existing === null || existing.length === 0) return `${MANAGED_BLOCK}\n`;
-
-  const starts = existing.split(INSTRUCTION_BLOCK_START).length - 1;
-  const ends = existing.split(INSTRUCTION_BLOCK_END).length - 1;
-  if (starts === 0 && ends === 0) return `${existing.trimEnd()}\n\n${MANAGED_BLOCK}\n`;
-  if (starts !== 1 || ends !== 1) {
-    throw new Error(`instruction file has a malformed skillmux managed block: ${path}`);
-  }
-
-  const start = existing.indexOf(INSTRUCTION_BLOCK_START);
-  const end = existing.indexOf(INSTRUCTION_BLOCK_END, start);
-  if (end < start) throw new Error(`instruction file has a malformed skillmux managed block: ${path}`);
-  return `${existing.slice(0, start)}${MANAGED_BLOCK}${existing.slice(end + INSTRUCTION_BLOCK_END.length)}`;
-}
-
-function planInstructionSetupWithResolver(
-  requestedAgents: readonly AgentId[],
-  resolvePath: (agent: AgentId) => string | undefined,
-  readFile: (path: string) => string | null,
-): InstructionPlan {
-  const changesByPath = new Map<string, InstructionChange>();
-  const manual: InstructionPlan["manual"] = [];
-
-  for (const agent of [...new Set(requestedAgents)]) {
-    const path = resolvePath(agent);
-    if (!path) {
-      manual.push({ agent, reason: "no safe durable user instruction file is known" });
-      continue;
-    }
-    const existingChange = changesByPath.get(path);
-    if (existingChange) {
-      existingChange.agents.push(agent);
-      continue;
-    }
-
-    const before = readFile(path);
-    const after = withManagedBlock(before, path);
-    changesByPath.set(path, {
-      path,
-      agents: [agent],
-      status: before === null ? "create" : before === after ? "unchanged" : "update",
-      before,
-      after,
-    });
-  }
-
-  return { changes: [...changesByPath.values()], manual };
-}
-
-export function planInstructionSetup(
-  requestedAgents: readonly AgentId[],
-  options: InstructionPlanOptions = {},
-): InstructionPlan {
-  const home = options.home ?? process.env.HOME ?? "";
-  const resolvedOptions = {
-    home,
-    codexHome: options.codexHome ?? process.env.CODEX_HOME ?? join(home, ".codex"),
-    claudeConfigDir: options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"),
-  };
-  return planInstructionSetupWithResolver(
-    requestedAgents,
-    (agent) => instructionPath(agent, resolvedOptions),
-    options.readFile ?? readInstructionFile,
-  );
-}
-
-function projectInstructionPath(agent: AgentId, projectRoot: string): string | undefined {
-  return getAgentDefinition(agent).instructions?.project?.(projectRoot);
-}
-
-export function planProjectInstructionSetup(
-  requestedAgents: readonly AgentId[],
-  projectRoot: string,
-  options: Pick<InstructionPlanOptions, "readFile"> = {},
-): InstructionPlan {
-  return planInstructionSetupWithResolver(
-    requestedAgents,
-    (agent) => projectInstructionPath(agent, projectRoot),
-    options.readFile ?? readInstructionFile,
-  );
-}
-
-function atomicWrite(path: string, content: string, mode: number): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  try {
-    writeFileSync(temporaryPath, content, { encoding: "utf8", mode });
-    renameSync(temporaryPath, path);
-  } finally {
-    rmSync(temporaryPath, { force: true });
-  }
-}
-
-export function applyInstructionPlan(plan: InstructionPlan): void {
-  for (const change of plan.changes) {
-    if (change.status === "unchanged") continue;
-    if (readInstructionFile(change.path) !== change.before) {
-      throw new Error(`instruction file changed after planning: ${change.path}`);
-    }
-  }
-
-  const applied: InstructionChange[] = [];
-  try {
-    for (const change of plan.changes) {
-      if (change.status === "unchanged") continue;
-      const mode = change.before === null ? 0o600 : statSync(change.path).mode;
-      atomicWrite(change.path, change.after, mode);
-      applied.push(change);
-    }
-  } catch (error) {
-    rollbackInstructionChanges(applied);
-    throw error;
-  }
-}
-
-function rollbackInstructionChanges(changes: InstructionChange[]): void {
-  for (const change of [...changes].reverse()) {
-    if (change.before === null) {
-      rmSync(change.path, { force: true });
-    } else {
-      atomicWrite(change.path, change.before, statSync(change.path).mode);
-    }
-  }
-}
-
-export function rollbackInstructionPlan(plan: InstructionPlan): void {
-  rollbackInstructionChanges(plan.changes.filter((change) => change.status !== "unchanged"));
-}

package/src/init.ts

@@ -1,390 +0,0 @@
-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 {
-  parseManifest,
-  resolveManifestPath,
-  serializeManifest,
-  type Manifest,
-  CORE_SKILL_LIMIT,
-  MANIFEST_FILENAME,
-} from "./manifest";
-import { BUILT_IN_TARGET_NAMES } from "./init-agents";
-import {
-  adoptTarget,
-  preflightAdoptTarget,
-  readSkillmuxMarker,
-  SKILLMUX_MARKER_FILENAME,
-} from "./sync";
-import { SKILL_ID_PATTERN } from "./vault";
-
-export const DEFAULT_SURFACE_CANDIDATES = ["~/.claude/skills", "~/.agents/skills"];
-
-/**
- * Test/ops escape hatch: comma-separated absolute paths overriding
- * DEFAULT_SURFACE_CANDIDATES. Not part of config.toml — "others as
- * configured" (spec.md) is deliberately left as an implementation-time
- * choice, same as the proposal heuristic. Exists primarily so tests never
- * probe the real $HOME's ~/.claude/skills or ~/.agents/skills.
- */
-export function surfaceCandidates(): string[] {
-  const override = process.env.SKILLMUX_INIT_SURFACES;
-  return override ? override.split(",").filter((p) => p.length > 0) : DEFAULT_SURFACE_CANDIDATES;
-}
-
-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 {
-  let count = 0;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory() && SKILL_ID_PATTERN.test(entry.name) && existsSync(join(dir, entry.name, "SKILL.md"))) {
-      count++;
-    }
-  }
-  return count;
-}
-
-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: false,
-      skillCount: countSkillDirs(path),
-      alreadyMarked: readSkillmuxMarker(path) !== null,
-      state: "directory",
-      deliveryMode: "managed-pins",
-    };
-  });
-}
-
-/**
- * Conservative default: no slash-command/workflow-router detection heuristic
- * at TDD time (spec.md, "skr init" AC) — evidence-only, nothing proposed
- * until a concrete heuristic is agreed.
- */
-export function proposeManifest(_candidates: SurfaceCandidate[]): Pick<Manifest, "core" | "project"> {
-  return { core: { skills: [] }, project: {} };
-}
-
-/** e.g. ~/.claude/skills -> "claude"; ~/.agents/skills -> "agents". */
-export function deriveTargetName(path: string): string {
-  return basename(dirname(path)).replace(/^\./, "").toLowerCase();
-}
-
-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);
-  }
-}
-
-/**
- * Writes skillmux.toml with the conservative-default core/project and the
- * confirmed targets, then adopts each confirmed dir in place (creating it
- * first if it doesn't exist yet). Unconfirmed candidates are simply never
- * passed in — this function never discovers paths on its own.
- */
-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 = {
-    ...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,
-            BUILT_IN_TARGET_NAMES.has(target.name)
-              ? existingTarget
-                ? { ...existingTarget, dir: undefined }
-                : { host: hostname(), project_groups: [] }
-              : existingTarget
-                ? { ...existingTarget, dir: target.dir }
-                : { dir: target.dir, host: hostname(), project_groups: [] },
-          ];
-        }),
-      ),
-    },
-  };
-  const effectiveLimit = manifest.core.limit ?? CORE_SKILL_LIMIT;
-  if (manifest.core.skills.length > effectiveLimit) {
-    throw new Error(
-      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${effectiveLimit}`,
-    );
-  }
-  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);
-      }
-    }
-
-    if (participant) {
-      participant.apply();
-      participantApplied = true;
-    }
-
-    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;
-}
-
-export const DISCOVERY_PARAGRAPH =
-  "Skills: only a curated core is loaded statically. Before improvising a " +
-  "multi-step workflow, or when a task smells like a domain you have no loaded " +
-  "skill for (career/resume, trading, SEO, i18n, design, one-off tooling), " +
-  "call `resolve_skill` with a one-line task description. `resolve_skill` " +
-  "returns a ranked shortlist; inspect candidates, fetch one or more " +
-  "relevant skills with `fetch_skill`, or ignore all and proceed normally " +
-  "when none are useful.";
-
-export const MCP_REGISTRATION_SNIPPET = JSON.stringify(
-  { mcpServers: { "skillmux": { command: "skillmux", args: ["serve"] } } },
-  null,
-  2,
-);
-
-/** §3.4 step 4: "print the last mile" — MCP registration command + discovery paragraph. */
-export function printLastMile(): string {
-  return [
-    "Register with your MCP client:",
-    MCP_REGISTRATION_SNIPPET,
-    "",
-    "Add this paragraph to your shared agent instructions (~80 tokens, the entire T3 discovery mechanism):",
-    DISCOVERY_PARAGRAPH,
-  ].join("\n");
-}