@systemdox/mcp-server 0.1.42 → 0.1.44

package/dist/install-skill.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+
+// src/install-skill.ts
+import { basename, resolve as resolve2 } from "path";
+
+// src/lib/cache.ts
+var ResponseCache = class {
+  store = /* @__PURE__ */ new Map();
+  ttlMs;
+  constructor(ttlMs) {
+    this.ttlMs = ttlMs;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.data;
+  }
+  set(key, data) {
+    this.store.set(key, {
+      data,
+      expiresAt: Date.now() + this.ttlMs
+    });
+  }
+  invalidate(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/lib/api-client.ts
+var SystemDoxApiClient = class {
+  config;
+  cache;
+  constructor(config) {
+    this.config = config;
+    this.cache = new ResponseCache(config.cacheTtlMs);
+  }
+  async validate() {
+    const res = await this.fetchRaw("/v1/health");
+    if (!res.ok) {
+      throw new Error(
+        `SystemDox API authentication failed (${res.status}). Check your SYSTEMDOX_API_KEY.`
+      );
+    }
+  }
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    const cacheKey = url.toString();
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0) return cached;
+    const res = await this.fetchRaw(path, params);
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${body}`);
+    }
+    const data = await res.json();
+    this.cache.set(cacheKey, data);
+    return data;
+  }
+  /** A read that skips the cache: an install must take the version that is
+   * latest now, not the one cached before someone published another. */
+  async getFresh(path) {
+    const res = await this.fetchRaw(path);
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${body}`);
+    }
+    return await res.json();
+  }
+  async post(path, body) {
+    return this.mutate("POST", path, body);
+  }
+  async put(path, body) {
+    return this.mutate("PUT", path, body);
+  }
+  async mutate(method, path, body) {
+    const url = this.buildUrl(path);
+    const res = await fetch(url, {
+      method,
+      headers: {
+        // The API Gateway authorizer only reads the Authorization header;
+        // X-API-Key is kept for backwards compatibility.
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "X-API-Key": this.config.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${text}`);
+    }
+    return await res.json();
+  }
+  invalidateCache(path) {
+    if (path) {
+      this.cache.invalidate(this.buildUrl(path).toString());
+    } else {
+      this.cache.clear();
+    }
+  }
+  buildUrl(path, params) {
+    const base = this.config.apiUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}${path.startsWith("/") ? "" : "/"}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    return url;
+  }
+  async fetchRaw(path, params) {
+    const url = this.buildUrl(path, params);
+    return fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "X-API-Key": this.config.apiKey,
+        Accept: "application/json"
+      }
+    });
+  }
+};
+
+// src/lib/config.ts
+var API_URL_DEFAULT = "https://api.puglieseweb.com/systemdox";
+function requireHttpsApiUrl(apiUrl) {
+  let parsed;
+  try {
+    parsed = new URL(apiUrl);
+  } catch {
+    throw new Error(
+      `SYSTEMDOX_API_URL is not a valid URL: ${apiUrl}`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `SYSTEMDOX_API_URL must use https:// \u2014 refusing to send the API key over ${parsed.protocol}// in cleartext. Got: ${apiUrl}`
+    );
+  }
+  return apiUrl;
+}
+function loadConfig() {
+  const apiKey = process.env.SYSTEMDOX_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "SYSTEMDOX_API_KEY is required. Generate one at your SystemDox settings page."
+    );
+  }
+  const apiUrl = requireHttpsApiUrl(
+    process.env.SYSTEMDOX_API_URL ?? API_URL_DEFAULT
+  );
+  return {
+    apiKey,
+    apiUrl,
+    cacheTtlMs: parseInt(process.env.SYSTEMDOX_CACHE_TTL ?? "300", 10) * 1e3,
+    defaultOrg: process.env.SYSTEMDOX_DEFAULT_ORG
+  };
+}
+
+// src/lib/skills.ts
+import { createHash } from "crypto";
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, relative, resolve, sep } from "path";
+var MANIFEST_FILE = ".systemdox-skill.json";
+var MAX_FILE_BYTES = 256 * 1024;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+var NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var SKIPPED = /* @__PURE__ */ new Set([MANIFEST_FILE, ".git", "node_modules", "__pycache__", ".DS_Store"]);
+var SkillInstallRefused = class extends Error {
+  constructor(dest, edited) {
+    super(
+      `${dest} has local changes in ${edited.length} file(s): ${edited.join(", ")}. Nothing was written. Move your changes aside, or install again with overwrite.`
+    );
+    this.dest = dest;
+    this.edited = edited;
+  }
+  dest;
+  edited;
+};
+function sha256(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function isValidName(name) {
+  return name.length <= 64 && NAME_RE.test(name);
+}
+function isValidPath(path) {
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+}
+function defaultSkillDir(name) {
+  return join(homedir(), ".claude", "skills", name);
+}
+async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (SKIPPED.has(entry.name) || entry.name.endsWith(".pyc")) continue;
+    const full = join(dir, entry.name);
+    const rel = relative(root, full).split(sep).join("/");
+    if (entry.isSymbolicLink()) out.links.push(rel);
+    else if (skipHidden && entry.name.startsWith(".")) out.hidden.push(rel);
+    else if (entry.isDirectory()) await walk(root, { skipHidden }, full, out);
+    else if (entry.isFile()) out.files.push(rel);
+  }
+  out.files.sort();
+  return out;
+}
+function within(dest, path) {
+  if (!isValidPath(path)) throw new Error(`refusing to write ${JSON.stringify(path)}: not a skill path`);
+  const full = resolve(dest, ...path.split("/"));
+  if (!full.startsWith(resolve(dest) + sep)) throw new Error(`refusing to write outside ${dest}: ${path}`);
+  return full;
+}
+async function readManifest(dest) {
+  try {
+    return JSON.parse(await readFile(join(dest, MANIFEST_FILE), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function installSkill(version, dest, { overwrite = false } = {}) {
+  if (!isValidName(version.name)) throw new Error(`refusing to install ${JSON.stringify(version.name)}: not a skill name`);
+  const incoming = new Map(version.files.map((f) => [f.path, f]));
+  for (const f of version.files) within(dest, f.path);
+  if (existsSync(dest) && (await lstat(dest)).isSymbolicLink()) {
+    throw new Error(`${dest} is a link: install into a real folder`);
+  }
+  const walked = existsSync(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
+  if (walked.links.length) {
+    throw new Error(`${dest} holds links (${walked.links.join(", ")}): remove them, nothing was written`);
+  }
+  const present = walked.files;
+  const manifest = await readManifest(dest);
+  const known = Object.fromEntries(
+    Object.entries(manifest?.files ?? {}).filter(([p, h]) => isValidPath(p) && typeof h === "string")
+  );
+  const edited = [];
+  const untracked = [];
+  for (const path of present) {
+    const content = await readFile(join(dest, ...path.split("/")), "utf8");
+    if (Object.hasOwn(known, path)) {
+      if (sha256(content) !== known[path]) edited.push(path);
+    } else if (!incoming.has(path) || sha256(content) !== incoming.get(path).sha256) {
+      if (incoming.has(path) || !manifest) edited.push(path);
+      else untracked.push(path);
+    }
+  }
+  const blocking = edited.filter((p) => incoming.has(p) || !manifest);
+  if (blocking.length && !overwrite) throw new SkillInstallRefused(dest, blocking);
+  const written = [];
+  for (const f of version.files) {
+    const full = within(dest, f.path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, f.content, "utf8");
+    written.push(f.path);
+  }
+  const removed = [];
+  const keptEdited = [];
+  for (const path of Object.keys(known)) {
+    if (incoming.has(path) || !present.includes(path)) continue;
+    if (edited.includes(path)) {
+      keptEdited.push(path);
+      continue;
+    }
+    await rm(within(dest, path));
+    removed.push(path);
+  }
+  const next = {
+    name: version.name,
+    version: version.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+  };
+  await writeFile(join(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
+  return {
+    dest,
+    version: version.version,
+    written,
+    removed,
+    keptUntracked: untracked.filter((p) => !incoming.has(p)),
+    keptEdited
+  };
+}
+function describeInstall(name, r) {
+  const lines = [
+    `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
+  ];
+  if (r.removed.length) lines.push(`Removed (no longer in the skill): ${r.removed.join(", ")}`);
+  if (r.keptEdited.length) {
+    lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
+  }
+  if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
+  lines.push("Start a new Claude Code session to load it.");
+  return lines.join("\n");
+}
+
+// src/install-skill.ts
+var INSTALL_USAGE = "Usage: systemdox-mcp-server install-skill <name> [--version <n>] [--target <dir>] [--overwrite]";
+function parseInstallArgs(argv) {
+  const args = { overwrite: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--overwrite") args.overwrite = true;
+    else if (a === "--version" || a === "--target") {
+      const value = argv[++i];
+      if (!value) throw new Error(`${a} needs a value
+${INSTALL_USAGE}`);
+      if (a === "--target") args.target = value;
+      else if (/^[1-9]\d*$/.test(value)) args.version = Number(value);
+      else throw new Error(`--version must be a whole number, got ${value}`);
+    } else if (a.startsWith("-")) throw new Error(`Unknown option ${a}
+${INSTALL_USAGE}`);
+    else if (!args.name) args.name = a;
+    else throw new Error(`Unexpected argument ${a}
+${INSTALL_USAGE}`);
+  }
+  if (!args.name) throw new Error(INSTALL_USAGE);
+  if (!isValidName(args.name)) throw new Error(`${args.name} is not a skill name`);
+  if (args.target && basename(resolve2(args.target)) !== args.name) {
+    throw new Error(`--target must be a folder named ${args.name} (e.g. .claude/skills/${args.name})`);
+  }
+  return args;
+}
+async function runInstallSkill(argv, io) {
+  let args;
+  try {
+    args = parseInstallArgs(argv);
+  } catch (e) {
+    io.err(e.message);
+    return 1;
+  }
+  let client = io.client;
+  if (!client) {
+    try {
+      client = new SystemDoxApiClient(loadConfig());
+    } catch (e) {
+      io.err(
+        `${e.message}
+Set SYSTEMDOX_API_KEY in your environment (create a key under Settings \u203A API keys in SystemDox), then run this again.`
+      );
+      return 1;
+    }
+  }
+  let version;
+  try {
+    version = await client.getFresh(
+      `/v1/standards/skills/${encodeURIComponent(args.name)}/versions/${args.version ?? "latest"}`
+    );
+  } catch (e) {
+    io.err(e.message);
+    return 1;
+  }
+  try {
+    const result = await installSkill(version, args.target ?? defaultSkillDir(version.name), {
+      overwrite: args.overwrite
+    });
+    io.out(describeInstall(version.name, result));
+    return 0;
+  } catch (e) {
+    io.err(e.message);
+    return e instanceof SkillInstallRefused ? 2 : 1;
+  }
+}
+export {
+  INSTALL_USAGE,
+  parseInstallArgs,
+  runInstallSkill
+};

package/dist/lib/api-client.d.ts

@@ -5,6 +5,9 @@ export declare class SystemDoxApiClient {
     constructor(config: ServerConfig);
     validate(): Promise<void>;
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    /** A read that skips the cache: an install must take the version that is
+     * latest now, not the one cached before someone published another. */
+    getFresh<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     private mutate;

package/dist/lib/api-client.js

@@ -60,6 +60,16 @@ var SystemDoxApiClient = class {
     this.cache.set(cacheKey, data);
     return data;
   }
+  /** A read that skips the cache: an install must take the version that is
+   * latest now, not the one cached before someone published another. */
+  async getFresh(path) {
+    const res = await this.fetchRaw(path);
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${body}`);
+    }
+    return await res.json();
+  }
   async post(path, body) {
     return this.mutate("POST", path, body);
   }

package/dist/lib/skills.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Authored skills on the local disk (ADR-216): read a skill folder to publish
+ * it, and install a published version into a folder without silently
+ * overwriting what someone edited there.
+ *
+ * Shared by the stdio server's publish_skill / install_skill tools and by the
+ * `install-skill` CLI command, so a skill installed either way leaves the same
+ * manifest and is refused on the same edits. The hosted (HTTP) server never
+ * calls the disk half: it cannot see the user's computer.
+ *
+ * The manifest `.systemdox-skill.json` records the version and every file's
+ * SHA-256 as installed. A file whose hash no longer matches was edited here;
+ * an install stops and names it unless asked to overwrite.
+ */
+export declare const MANIFEST_FILE = ".systemdox-skill.json";
+export declare const ENTRY_FILE = "SKILL.md";
+/** The server's limits (backend common/authored_skills.py), checked early so
+ * a local mistake is named before anything is sent. */
+export declare const MAX_FILES = 100;
+export declare const MAX_FILE_BYTES: number;
+export declare const MAX_TOTAL_BYTES: number;
+export interface SkillFileIn {
+    path: string;
+    content: string;
+}
+export interface SkillFileOut extends SkillFileIn {
+    bytes: number;
+    sha256: string;
+}
+export interface SkillVersionFiles {
+    name: string;
+    version: number;
+    description: string;
+    publishedAt: string;
+    publishedBy?: string;
+    files: SkillFileOut[];
+}
+export interface SkillManifest {
+    name: string;
+    version: number;
+    installedAt: string;
+    files: Record<string, string>;
+}
+export interface InstallResult {
+    dest: string;
+    version: number;
+    written: string[];
+    removed: string[];
+    /** Files someone added here that the skill does not ship: left alone. */
+    keptUntracked: string[];
+    /** Edited files the new version no longer ships: left alone. */
+    keptEdited: string[];
+}
+export declare class SkillInstallRefused extends Error {
+    readonly dest: string;
+    readonly edited: string[];
+    constructor(dest: string, edited: string[]);
+}
+export declare function sha256(content: string): string;
+export declare function isValidName(name: string): boolean;
+export declare function isValidPath(path: string): boolean;
+/** `name` from SKILL.md's frontmatter, or undefined. */
+export declare function frontmatterName(skillMd: string): string | undefined;
+/** The default install folder: personal skills, every project (ADR-216 §6 Q1). */
+export declare function defaultSkillDir(name: string): string;
+/**
+ * Read a skill folder exactly as it is on disk (bytes decoded as UTF-8, never
+ * re-typed), ready to publish. Throws naming the first file that cannot be
+ * part of a skill.
+ */
+export declare function readSkillDirectory(directory: string): Promise<{
+    name: string;
+    files: SkillFileIn[];
+    skipped: string[];
+}>;
+/**
+ * Write a published version into `dest`. Stops before writing anything when
+ * a file there was edited since it was installed (or the folder holds files
+ * with no manifest to vouch for them), unless `overwrite`.
+ */
+export declare function installSkill(version: SkillVersionFiles, dest: string, { overwrite }?: {
+    overwrite?: boolean;
+}): Promise<InstallResult>;
+/** A fence longer than any backtick run in `text`, so content cannot close it. */
+export declare function fenceFor(text: string): string;
+/** Human summary of an install, shared by the tool and the CLI. */
+export declare function describeInstall(name: string, r: InstallResult): string;

package/dist/lib/skills.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+// src/lib/skills.ts
+import { createHash } from "crypto";
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, relative, resolve, sep } from "path";
+var MANIFEST_FILE = ".systemdox-skill.json";
+var ENTRY_FILE = "SKILL.md";
+var MAX_FILES = 100;
+var MAX_FILE_BYTES = 256 * 1024;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+var NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var SKIPPED = /* @__PURE__ */ new Set([MANIFEST_FILE, ".git", "node_modules", "__pycache__", ".DS_Store"]);
+var SkillInstallRefused = class extends Error {
+  constructor(dest, edited) {
+    super(
+      `${dest} has local changes in ${edited.length} file(s): ${edited.join(", ")}. Nothing was written. Move your changes aside, or install again with overwrite.`
+    );
+    this.dest = dest;
+    this.edited = edited;
+  }
+  dest;
+  edited;
+};
+function sha256(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function isValidName(name) {
+  return name.length <= 64 && NAME_RE.test(name);
+}
+function isValidPath(path) {
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+}
+function frontmatterName(skillMd) {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+  if (!block) return void 0;
+  const line = /^name:[ \t]*(.+?)[ \t]*$/m.exec(block[1]);
+  return line ? line[1].replace(/^(['"])(.*)\1$/, "$2") : void 0;
+}
+function defaultSkillDir(name) {
+  return join(homedir(), ".claude", "skills", name);
+}
+async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (SKIPPED.has(entry.name) || entry.name.endsWith(".pyc")) continue;
+    const full = join(dir, entry.name);
+    const rel = relative(root, full).split(sep).join("/");
+    if (entry.isSymbolicLink()) out.links.push(rel);
+    else if (skipHidden && entry.name.startsWith(".")) out.hidden.push(rel);
+    else if (entry.isDirectory()) await walk(root, { skipHidden }, full, out);
+    else if (entry.isFile()) out.files.push(rel);
+  }
+  out.files.sort();
+  return out;
+}
+async function readSkillDirectory(directory) {
+  const root = resolve(directory);
+  if (!existsSync(join(root, ENTRY_FILE))) {
+    throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
+  }
+  const walked = await walk(root, { skipHidden: true });
+  if (walked.links.length) {
+    throw new Error(`${walked.links.join(", ")}: links are not followed; copy the file into the skill folder`);
+  }
+  const paths = walked.files;
+  if (paths.length > MAX_FILES) {
+    throw new Error(`${root} holds ${paths.length} files: a skill holds at most ${MAX_FILES}`);
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const files = [];
+  let total = 0;
+  for (const path of paths) {
+    if (!isValidPath(path)) {
+      throw new Error(`${path}: file names may use letters, digits, ".", "_" and "-" only`);
+    }
+    const raw = await readFile(join(root, ...path.split("/")));
+    if (raw.includes(0)) throw new Error(`${path} is binary: a skill holds text files only`);
+    if (raw.length > MAX_FILE_BYTES) {
+      throw new Error(`${path} is ${raw.length} bytes: a file holds at most ${MAX_FILE_BYTES}`);
+    }
+    total += raw.length;
+    if (total > MAX_TOTAL_BYTES) {
+      throw new Error(`the files pass ${MAX_TOTAL_BYTES} bytes at ${path}`);
+    }
+    let content;
+    try {
+      content = decoder.decode(raw);
+    } catch {
+      throw new Error(`${path} is not UTF-8 text`);
+    }
+    files.push({ path, content });
+  }
+  const skillMd = files.find((f) => f.path === ENTRY_FILE);
+  const name = frontmatterName(skillMd.content);
+  if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name`);
+  return { name, files, skipped: walked.hidden };
+}
+function within(dest, path) {
+  if (!isValidPath(path)) throw new Error(`refusing to write ${JSON.stringify(path)}: not a skill path`);
+  const full = resolve(dest, ...path.split("/"));
+  if (!full.startsWith(resolve(dest) + sep)) throw new Error(`refusing to write outside ${dest}: ${path}`);
+  return full;
+}
+async function readManifest(dest) {
+  try {
+    return JSON.parse(await readFile(join(dest, MANIFEST_FILE), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function installSkill(version, dest, { overwrite = false } = {}) {
+  if (!isValidName(version.name)) throw new Error(`refusing to install ${JSON.stringify(version.name)}: not a skill name`);
+  const incoming = new Map(version.files.map((f) => [f.path, f]));
+  for (const f of version.files) within(dest, f.path);
+  if (existsSync(dest) && (await lstat(dest)).isSymbolicLink()) {
+    throw new Error(`${dest} is a link: install into a real folder`);
+  }
+  const walked = existsSync(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
+  if (walked.links.length) {
+    throw new Error(`${dest} holds links (${walked.links.join(", ")}): remove them, nothing was written`);
+  }
+  const present = walked.files;
+  const manifest = await readManifest(dest);
+  const known = Object.fromEntries(
+    Object.entries(manifest?.files ?? {}).filter(([p, h]) => isValidPath(p) && typeof h === "string")
+  );
+  const edited = [];
+  const untracked = [];
+  for (const path of present) {
+    const content = await readFile(join(dest, ...path.split("/")), "utf8");
+    if (Object.hasOwn(known, path)) {
+      if (sha256(content) !== known[path]) edited.push(path);
+    } else if (!incoming.has(path) || sha256(content) !== incoming.get(path).sha256) {
+      if (incoming.has(path) || !manifest) edited.push(path);
+      else untracked.push(path);
+    }
+  }
+  const blocking = edited.filter((p) => incoming.has(p) || !manifest);
+  if (blocking.length && !overwrite) throw new SkillInstallRefused(dest, blocking);
+  const written = [];
+  for (const f of version.files) {
+    const full = within(dest, f.path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, f.content, "utf8");
+    written.push(f.path);
+  }
+  const removed = [];
+  const keptEdited = [];
+  for (const path of Object.keys(known)) {
+    if (incoming.has(path) || !present.includes(path)) continue;
+    if (edited.includes(path)) {
+      keptEdited.push(path);
+      continue;
+    }
+    await rm(within(dest, path));
+    removed.push(path);
+  }
+  const next = {
+    name: version.name,
+    version: version.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+  };
+  await writeFile(join(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
+  return {
+    dest,
+    version: version.version,
+    written,
+    removed,
+    keptUntracked: untracked.filter((p) => !incoming.has(p)),
+    keptEdited
+  };
+}
+function fenceFor(text) {
+  const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((r) => r.length));
+  return "`".repeat(Math.max(3, longest + 1));
+}
+function describeInstall(name, r) {
+  const lines = [
+    `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
+  ];
+  if (r.removed.length) lines.push(`Removed (no longer in the skill): ${r.removed.join(", ")}`);
+  if (r.keptEdited.length) {
+    lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
+  }
+  if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
+  lines.push("Start a new Claude Code session to load it.");
+  return lines.join("\n");
+}
+export {
+  ENTRY_FILE,
+  MANIFEST_FILE,
+  MAX_FILES,
+  MAX_FILE_BYTES,
+  MAX_TOTAL_BYTES,
+  SkillInstallRefused,
+  defaultSkillDir,
+  describeInstall,
+  fenceFor,
+  frontmatterName,
+  installSkill,
+  isValidName,
+  isValidPath,
+  readSkillDirectory,
+  sha256
+};