@xenonbyte/xsk 0.1.0

package/lib/uninstall.js

@@ -0,0 +1,577 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  read,
+  write,
+  validate,
+  validateOperationalSemantics,
+  create,
+  defaultXskRoot,
+  removeManifest,
+  manifestPath,
+  atomicWriteFile,
+  isInsideDir,
+} = require('./manifest');
+const { get } = require('./skills');
+const { buildSkill } = require('./generator');
+const {
+  MARKER,
+  PACKAGE_NAME,
+  isSymlink,
+  hasUnsafeSkillPath,
+  hasValidMarker,
+  safeBackupForSkill,
+} = require('./ownership');
+const { contentSha256 } = require('./content-hash');
+
+const PARTIAL_EXIT = 2;
+const FAILURE_EXIT = 1;
+
+function generatedContentFor(skillName) {
+  const skill = get(skillName);
+  if (!skill) return null;
+  try {
+    return buildSkill(skill).content;
+  } catch (e) {
+    return null;
+  }
+}
+
+function classifyPaths(installedPaths) {
+  const skillDirs = new Set();
+  for (const p of installedPaths) {
+    const base = path.basename(p);
+    if (base === 'SKILL.md' || base === MARKER) {
+      skillDirs.add(path.dirname(p));
+    } else {
+      skillDirs.add(p);
+    }
+  }
+  return [...skillDirs];
+}
+
+function restoreOwnershipMarker(markerFile) {
+  try {
+    atomicWriteFile(markerFile, `${PACKAGE_NAME}\n`, {
+      dirLabel: 'marker dir',
+      tempLabel: 'marker temp file',
+      targetLabel: 'marker file',
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function installedHashByTarget(manifest) {
+  const records = Array.isArray(manifest.installed_hashes) ? manifest.installed_hashes : [];
+  return new Map(records.map((r) => [r.target, r.sha256]));
+}
+
+function retainedInstalledHashes(manifest, retainedPaths) {
+  const retained = new Set(retainedPaths);
+  return (Array.isArray(manifest.installed_hashes) ? manifest.installed_hashes : [])
+    .filter((r) => retained.has(r.target))
+    .map((r) => ({ target: r.target, sha256: r.sha256 }));
+}
+
+function appendError(current, message) {
+  return current ? `${current}; ${message}` : message;
+}
+
+function validateBackupTargets(backups, skillDirs, skillsRoot) {
+  const skillFiles = new Set(skillDirs.map((skillDir) => path.join(skillDir, 'SKILL.md')));
+  const seenTargets = new Set();
+  for (const backup of backups) {
+    if (seenTargets.has(backup.target)) {
+      return { valid: false, reason: `duplicate backup target: ${backup.target}` };
+    }
+    seenTargets.add(backup.target);
+    if (!isInsideDir(backup.target, skillsRoot)) {
+      return { valid: false, reason: `backup target escapes platform root: ${backup.target}` };
+    }
+    if (path.basename(backup.target) !== 'SKILL.md') {
+      return { valid: false, reason: `backup target is not a skill file: ${backup.target}` };
+    }
+    if (!skillFiles.has(backup.target)) {
+      return { valid: false, reason: `backup target is not installed: ${backup.target}` };
+    }
+  }
+  return { valid: true };
+}
+
+function capturePathState(targetPath) {
+  try {
+    const stat = fs.lstatSync(targetPath);
+    if (stat.isDirectory()) {
+      return { exists: true, type: 'directory', mode: stat.mode };
+    }
+    if (stat.isSymbolicLink()) {
+      return { exists: true, type: 'symlink', link: fs.readlinkSync(targetPath) };
+    }
+    if (stat.isFile()) {
+      return { exists: true, type: 'file', content: fs.readFileSync(targetPath), mode: stat.mode };
+    }
+    return { exists: true, type: 'other' };
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) {
+      return { exists: false };
+    }
+    throw e;
+  }
+}
+
+function removePathForRestore(targetPath) {
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function restorePathState(targetPath, state) {
+  if (!state.exists) {
+    removePathForRestore(targetPath);
+    return;
+  }
+  if (state.type === 'directory') {
+    if (fs.existsSync(targetPath) && !fs.lstatSync(targetPath).isDirectory()) {
+      removePathForRestore(targetPath);
+    }
+    fs.mkdirSync(targetPath, { recursive: true, mode: state.mode });
+    try {
+      fs.chmodSync(targetPath, state.mode);
+    } catch (e) {
+      /* best effort */
+    }
+    return;
+  }
+  removePathForRestore(targetPath);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  if (state.type === 'symlink') {
+    fs.symlinkSync(state.link, targetPath);
+    return;
+  }
+  if (state.type === 'file') {
+    fs.writeFileSync(targetPath, state.content, { mode: state.mode });
+    try {
+      fs.chmodSync(targetPath, state.mode);
+    } catch (e) {
+      /* best effort */
+    }
+  }
+}
+
+function createRollbackJournal() {
+  const states = new Map();
+  return {
+    capture(targetPath) {
+      if (!states.has(targetPath)) {
+        states.set(targetPath, capturePathState(targetPath));
+      }
+    },
+    restore() {
+      const entries = [...states.entries()].reverse();
+      for (const [targetPath, state] of entries) {
+        restorePathState(targetPath, state);
+      }
+    },
+  };
+}
+
+function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
+  let manifest;
+  try {
+    manifest = read(platform, { xskRoot });
+  } catch (e) {
+    return {
+      platform,
+      invalid: true,
+      removed: [],
+      restored: [],
+      retained: [],
+      skipped: [],
+      refused: [],
+      partial: false,
+      error: `manifest for ${platform} is not valid JSON: ${e.message}`,
+      exitCode: FAILURE_EXIT,
+    };
+  }
+
+  if (!manifest) {
+    return {
+      platform,
+      nothingInstalled: true,
+      removed: [],
+      restored: [],
+      retained: [],
+      skipped: [],
+      refused: [],
+      partial: false,
+      exitCode: 0,
+    };
+  }
+
+  if (!validate(manifest, { expectedPlatform: platform })) {
+    return {
+      platform,
+      invalid: true,
+      removed: [],
+      restored: [],
+      retained: [],
+      skipped: [],
+      refused: [],
+      partial: false,
+      error: `manifest for ${platform} failed shape validation; refusing to uninstall`,
+      exitCode: FAILURE_EXIT,
+    };
+  }
+
+  const sem = validateOperationalSemantics({ platform, skillsRoot, manifest });
+  if (!sem.valid) {
+    return {
+      platform,
+      invalid: true,
+      removed: [],
+      restored: [],
+      retained: [],
+      skipped: [],
+      refused: [],
+      partial: false,
+      error: sem.reason,
+      exitCode: FAILURE_EXIT,
+    };
+  }
+
+  const backups = manifest.backups || [];
+  const skillDirs = classifyPaths(manifest.installed_paths);
+  const backupTargets = validateBackupTargets(backups, skillDirs, skillsRoot);
+  if (!backupTargets.valid) {
+    return {
+      platform,
+      invalid: true,
+      removed: [],
+      restored: [],
+      retained: [],
+      skipped: [],
+      refused: [],
+      partial: false,
+      error: backupTargets.reason,
+      exitCode: FAILURE_EXIT,
+    };
+  }
+
+  const removed = [];
+  const restored = [];
+  const retainedFiles = [];
+  const retainedMarkers = [];
+  const retainedDirs = [];
+  const retainedBackups = [];
+  const skipped = [];
+  const refused = [];
+  const installedHashes = installedHashByTarget(manifest);
+  const rollbackJournal = createRollbackJournal();
+  let partial = false;
+  let error = null;
+  const manifestPaths = new Set(manifest.installed_paths);
+
+  const ownedDirs = new Set(
+    manifest.installed_paths.filter((p) => {
+      const base = path.basename(p);
+      return base !== 'SKILL.md' && base !== MARKER;
+    }),
+  );
+  for (const skillDir of skillDirs) {
+    const skillName = path.basename(skillDir);
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    const markerFile = path.join(skillDir, MARKER);
+    const backupState = safeBackupForSkill(backups, skillFile, xskRoot, platform, skillsRoot);
+    const skillRollbackJournal = createRollbackJournal();
+    const captureSkillMutation = (targetPath) => {
+      rollbackJournal.capture(targetPath);
+      skillRollbackJournal.capture(targetPath);
+    };
+    const pathUnsafe = hasUnsafeSkillPath(skillDir, skillFile, markerFile);
+    const markerInvalid = !pathUnsafe && fs.existsSync(markerFile) && !hasValidMarker(markerFile);
+
+    if (
+      pathUnsafe ||
+      markerInvalid ||
+      backupState.unsafe
+    ) {
+      refused.push(skillDir);
+      if (pathUnsafe) {
+        if (ownedDirs.has(skillDir)) {
+          retainedDirs.push(skillDir);
+        }
+        if (manifestPaths.has(skillFile)) {
+          retainedFiles.push(skillFile);
+        }
+        if (manifestPaths.has(markerFile)) {
+          retainedMarkers.push(markerFile);
+        }
+        if (backupState.backup) {
+          retainedBackups.push(backupState.backup);
+        }
+      } else {
+        if (ownedDirs.has(skillDir) && fs.existsSync(skillDir)) {
+          retainedDirs.push(skillDir);
+        }
+        if ((backupState.unsafe || markerInvalid) && fs.existsSync(skillFile)) {
+          retainedFiles.push(skillFile);
+        }
+        if ((backupState.unsafe || markerInvalid) && fs.existsSync(markerFile)) {
+          retainedMarkers.push(markerFile);
+        }
+        if (backupState.backup) {
+          retainedBackups.push(backupState.backup);
+        }
+      }
+      partial = true;
+      continue;
+    }
+
+    if (backupState.missing) {
+      refused.push(skillDir);
+      if (ownedDirs.has(skillDir) && fs.existsSync(skillDir)) {
+        retainedDirs.push(skillDir);
+      }
+      if (fs.existsSync(skillFile)) {
+        retainedFiles.push(skillFile);
+      }
+      if (fs.existsSync(markerFile)) {
+        retainedMarkers.push(markerFile);
+      }
+      retainedBackups.push(backupState.backup);
+      partial = true;
+      continue;
+    }
+
+    if (!fs.existsSync(markerFile)) {
+      const retainedDir = ownedDirs.has(skillDir) && fs.existsSync(skillDir);
+      const retainedFile = fs.existsSync(skillFile);
+      const bk = backupState.backup;
+      skipped.push(skillDir);
+      if (retainedDir) {
+        retainedDirs.push(skillDir);
+      }
+      if (retainedFile) {
+        retainedFiles.push(skillFile);
+      }
+      if (retainedDir || retainedFile || bk) {
+        retainedMarkers.push(markerFile);
+        if (bk) {
+          retainedBackups.push(bk);
+        }
+        partial = true;
+      }
+      continue;
+    }
+
+    const fileExists = fs.existsSync(skillFile);
+    let fileModified = false;
+    if (fileExists) {
+      const onDisk = fs.readFileSync(skillFile);
+      const installedHash = installedHashes.get(skillFile);
+      if (installedHash) {
+        fileModified = contentSha256(onDisk) !== installedHash;
+      } else {
+        const gen = generatedContentFor(skillName);
+        fileModified = gen === null ? true : onDisk.toString('utf8') !== gen;
+      }
+    }
+
+    if (!fileExists || !fileModified) {
+      let removedSkillFile = false;
+      if (fileExists) {
+        captureSkillMutation(skillFile);
+        fs.rmSync(skillFile, { force: true });
+        removedSkillFile = true;
+      }
+      const bk = backupState.backup;
+      if (bk && fs.existsSync(bk.backup)) {
+        captureSkillMutation(bk.target);
+        rollbackJournal.capture(bk.backup);
+        fs.mkdirSync(path.dirname(bk.target), { recursive: true });
+        try {
+          fs.copyFileSync(bk.backup, bk.target);
+        } catch (e) {
+          let rollbackError = null;
+          try {
+            skillRollbackJournal.restore();
+          } catch (rollbackErr) {
+            rollbackError = rollbackErr;
+          }
+          partial = true;
+          error = appendError(error, `backup restore failed: ${e.message}`);
+          if (rollbackError) {
+            error = appendError(error, `rollback failed: ${rollbackError.message}`);
+          }
+          if (ownedDirs.has(skillDir) && fs.existsSync(skillDir)) {
+            retainedDirs.push(skillDir);
+          }
+          if (fs.existsSync(skillFile)) {
+            retainedFiles.push(skillFile);
+          }
+          if (fs.existsSync(markerFile)) {
+            retainedMarkers.push(markerFile);
+          }
+          retainedBackups.push(bk);
+          continue;
+        }
+        try {
+          fs.rmSync(bk.backup, { force: true });
+        } catch (e) {
+          let rollbackError = null;
+          try {
+            skillRollbackJournal.restore();
+          } catch (rollbackErr) {
+            rollbackError = rollbackErr;
+          }
+          partial = true;
+          error = appendError(error, `backup cleanup failed: ${e.message}`);
+          if (rollbackError) {
+            error = appendError(error, `rollback failed: ${rollbackError.message}`);
+          }
+          if (ownedDirs.has(skillDir) && fs.existsSync(skillDir)) {
+            retainedDirs.push(skillDir);
+          }
+          if (fs.existsSync(skillFile)) {
+            retainedFiles.push(skillFile);
+          }
+          if (fs.existsSync(markerFile)) {
+            retainedMarkers.push(markerFile);
+          }
+          retainedBackups.push(bk);
+          continue;
+        }
+        restored.push(bk.target);
+      }
+      if (removedSkillFile) {
+        removed.push(skillFile);
+      }
+      if (ownedDirs.has(skillDir)) {
+        let markerRemoved = false;
+        if (fs.existsSync(markerFile)) {
+          captureSkillMutation(markerFile);
+          fs.rmSync(markerFile, { force: true });
+          markerRemoved = true;
+        }
+        try {
+          captureSkillMutation(skillDir);
+          fs.rmdirSync(skillDir);
+          if (markerRemoved) {
+            removed.push(markerFile);
+          }
+          removed.push(skillDir);
+        } catch (e) {
+          if (fs.existsSync(skillDir)) {
+            if (markerRemoved && restoreOwnershipMarker(markerFile)) {
+              retainedMarkers.push(markerFile);
+            }
+            retainedDirs.push(skillDir);
+            partial = true;
+          } else if (markerRemoved) {
+            removed.push(markerFile);
+          }
+        }
+      } else if (fs.existsSync(markerFile)) {
+        captureSkillMutation(markerFile);
+        fs.rmSync(markerFile, { force: true });
+        removed.push(markerFile);
+      }
+    } else {
+      if (ownedDirs.has(skillDir)) {
+        retainedDirs.push(skillDir);
+      }
+      retainedFiles.push(skillFile);
+      retainedMarkers.push(markerFile);
+      const bk = backupState.backup;
+      if (bk) {
+        retainedBackups.push(bk);
+      }
+      partial = true;
+    }
+  }
+
+  const retainedPaths = [...retainedDirs, ...retainedFiles, ...retainedMarkers];
+  let narrowed = null;
+  if (retainedPaths.length > 0 || retainedBackups.length > 0) {
+    narrowed = create(platform, manifest.version);
+    narrowed.installed_paths = retainedPaths;
+    narrowed.backups = retainedBackups;
+    narrowed.installed_hashes = retainedInstalledHashes(manifest, retainedFiles);
+    try {
+      rollbackJournal.capture(manifestPath(platform, { xskRoot }));
+      write(platform, narrowed, { xskRoot });
+    } catch (e) {
+      partial = true;
+      narrowed = manifest;
+      error = appendError(error, `manifest write failed: ${e.message}`);
+      try {
+        rollbackJournal.restore();
+        // Full rollback restored every removed/restored path, so the prior
+        // removal tallies no longer reflect disk state. Clear them so callers
+        // do not report removals that were undone.
+        removed.length = 0;
+        restored.length = 0;
+      } catch (rollbackErr) {
+        error = appendError(error, `rollback failed: ${rollbackErr.message}`);
+      }
+    }
+  } else {
+    try {
+      removeManifest(platform, { xskRoot });
+    } catch (e) {
+      partial = true;
+      narrowed = manifest;
+      error = `manifest removal failed: ${e.message}`;
+    }
+  }
+
+  const result = {
+    platform,
+    removed,
+    restored,
+    retained: retainedFiles,
+    skipped,
+    refused,
+    partial,
+    manifest: narrowed,
+    exitCode: partial ? PARTIAL_EXIT : 0,
+  };
+  if (error) {
+    result.error = error;
+  }
+  return result;
+}
+
+function uninstall(options) {
+  const opts = options || {};
+  const platforms = opts.platforms || ['claude', 'codex', 'opencode', 'gemini'];
+  const xskRoot = opts.xskRoot || defaultXskRoot();
+  const { rootFor } = require('./install');
+
+  const summary = { platforms: {} };
+  let exitCode = 0;
+  for (const platform of platforms) {
+    const skillsRoot = rootFor(platform, opts.platformRoots);
+    const res = uninstallPlatform({ platform, xskRoot, skillsRoot });
+    summary.platforms[platform] = res;
+    if (res.exitCode > exitCode) {
+      exitCode = res.exitCode;
+    }
+  }
+  summary.exitCode = exitCode;
+  return summary;
+}
+
+module.exports = {
+  uninstall,
+  uninstallPlatform,
+  classifyPaths,
+  generatedContentFor,
+  isSymlink,
+  safeBackupForSkill,
+  PARTIAL_EXIT,
+  FAILURE_EXIT,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@xenonbyte/xsk",
+  "version": "0.1.0",
+  "description": "Agent skill aggregator. Install a curated set of agent skills across Claude Code, Codex, opencode, and Gemini with manifest-backed safety.",
+  "license": "MIT",
+  "bin": {
+    "xsk": "bin/xsk.js"
+  },
+  "main": "bin/xsk.js",
+  "scripts": {
+    "test": "node --test",
+    "syntaxcheck": "node scripts/syntaxcheck.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "shared/",
+    "templates/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent",
+    "skills",
+    "claude-code",
+    "codex",
+    "opencode",
+    "gemini",
+    "cli"
+  ]
+}

package/shared/skill-common.md

@@ -0,0 +1,6 @@
+## Conventions shared across xsk skills
+
+- Triggers are matched by intent, not by exact wording. The phrases listed under "When to use" are cues, not a required incantation.
+- Write in natural, direct prose. No formulaic openers, no filler conclusions, no restating the request before you answer it.
+- When a decision would change the implementation, surface it as a short question and let the user decide. Do not pick silently.
+- These are instruction skills. They shape how work is approached, not what the agent is technically capable of.

package/skills/archive-req/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: xsk-archive-req
+description: Archive the active requirement document into requirements/archive/ and leave zero active docs.
+---
+
+# xsk-archive-req
+
+Archive the active requirement document into `requirements/archive/`. After it runs, zero active requirement docs remain.
+
+## When to use
+
+Match the intent, not the exact words. Common cues:
+
+- "归档需求", "需求归档", "把这个需求存档"
+- "archive requirement"
+- any request to file away the current active requirement doc
+
+## How it works
+
+1. Scan `requirements/*.md` (excluding `requirements/archive/`) for the single document whose frontmatter has `status: active`. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
+2. If there is no active document, refuse with a one-line reason and stop. Do not archive anything.
+3. Read the active doc slug and validate it against `^[a-z0-9]+(-[a-z0-9]+)*$`. If the slug is missing/invalid, stop with the reason before any write.
+4. Check the archive target `requirements/archive/<slug>.md`. If it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing.
+5. Write the fully-updated archived content to `requirements/archive/<slug>.md`: set `status: archived`, add `archived_at: <ISO date>`, and preserve every other frontmatter field and the entire body unchanged.
+6. Confirm it landed as written, then remove the source active doc.
+7. After archiving, confirm zero active documents remain.
+
+## Output
+
+Either a one-line refusal that names the missing/invalid slug, a stop-and-ask response when `requirements/archive/<slug>.md` already exists and it was left unchanged, writing nothing, or the archived path (`requirements/archive/<slug>.md`) plus confirmation that it landed before the source active doc was removed and that no active requirement docs remain.
+
+## Conventions shared across xsk skills
+
+- Triggers are matched by intent, not by exact wording. The phrases listed under "When to use" are cues, not a required incantation.
+- Write in natural, direct prose. No formulaic openers, no filler conclusions, no restating the request before you answer it.
+- When a decision would change the implementation, surface it as a short question and let the user decide. Do not pick silently.
+- These are instruction skills. They shape how work is approached, not what the agent is technically capable of.

package/skills/bypass-claude/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: xsk-bypass-claude
+description: Set the current project to Claude Code bypass-permissions mode by writing .claude/settings.local.json. Claude only.
+---
+
+# xsk-bypass-claude
+
+Set the current project to Claude Code bypass-permissions mode (auto-approve tools) by writing `.claude/settings.local.json`. This is a Claude Code-only skill; it has no effect on Codex, opencode, or Gemini.
+
+## When to use
+
+Match the intent, not the exact words. Common cues:
+
+- "bypass permissions", "auto approve", "set bypassPermissions"
+- "跳过权限", "免确认", "设置 bypassPermissions"
+- any request to make Claude Code stop asking for tool approval in the current project
+
+## How it works
+
+Operate on the **current project directory** only. The target is always `.claude/settings.local.json`.
+
+1. If the current agent is not Claude Code, refuse the request, state that this is a Claude Code-only skill, write nothing, and stop.
+
+2. Never write or modify `.claude/settings.json`.
+
+3. If `.claude/settings.local.json` does not exist, create the `.claude/` directory and write exactly:
+
+   ```json
+   {
+     "permissions": {
+       "defaultMode": "bypassPermissions"
+     }
+   }
+   ```
+
+4. If `.claude/settings.local.json` already exists, read it. If the file is invalid JSON or is not a JSON object, report that `.claude/settings.local.json` is malformed, write nothing, and stop.
+
+5. Otherwise, set only `permissions.defaultMode` to `"bypassPermissions"` in `.claude/settings.local.json`, preserve every other field and its value, and write back with 2-space indentation and a trailing newline. Do not reorder, reformat, or drop existing keys.
+
+6. If `permissions.defaultMode` is already `"bypassPermissions"`, make no change (idempotent no-op).
+
+`permissions.defaultMode = "bypassPermissions"` is the verified Claude Code setting for auto-approving tools.
+
+## Output
+
+Report only the path written (`.claude/settings.local.json`) and that `permissions.defaultMode` is `bypassPermissions`. Do not include preserved setting values. Take no further action.
+
+## Conventions shared across xsk skills
+
+- Triggers are matched by intent, not by exact wording. The phrases listed under "When to use" are cues, not a required incantation.
+- Write in natural, direct prose. No formulaic openers, no filler conclusions, no restating the request before you answer it.
+- When a decision would change the implementation, surface it as a short question and let the user decide. Do not pick silently.
+- These are instruction skills. They shape how work is approached, not what the agent is technically capable of.