@xenonbyte/xsk 0.1.0

package/lib/manifest.js

@@ -0,0 +1,288 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { isSha256 } = require('./content-hash');
+
+const SCHEMA_VERSION = 1;
+const REQUIRED_FIELDS = [
+  'schema_version',
+  'platform',
+  'version',
+  'installed_at',
+  'installed_paths',
+  'backups',
+];
+const ATOMIC_WRITE_ATTEMPTS = 10;
+
+function defaultXskRoot() {
+  return path.join(os.homedir(), '.xsk');
+}
+
+function manifestPath(platform, options) {
+  const opts = options || {};
+  const root = opts.xskRoot || defaultXskRoot();
+  return path.join(root, 'manifests', `${platform}.manifest`);
+}
+
+function pathSegments(targetPath) {
+  const segments = [];
+  let current = path.resolve(targetPath);
+  while (true) {
+    segments.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return segments.reverse();
+}
+
+function assertSafePath(targetPath, label, options) {
+  const opts = options || {};
+  const target = path.resolve(targetPath);
+  for (const segment of pathSegments(target)) {
+    let stat;
+    try {
+      stat = fs.lstatSync(segment);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') continue;
+      throw e;
+    }
+    const parent = path.dirname(segment);
+    const isTopLevel = parent === path.dirname(parent);
+    if (stat.isSymbolicLink() && isTopLevel) {
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(`refusing to operate through symlinked ${label}: ${segment}`);
+    }
+    const isTarget = segment === target;
+    if (!stat.isDirectory() && !(isTarget && opts.allowNonDirectoryTarget)) {
+      throw new Error(`refusing to operate through non-directory ${label} ancestor: ${segment}`);
+    }
+  }
+}
+
+function isSafePath(targetPath, label, options) {
+  try {
+    assertSafePath(targetPath, label, options);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function isInsideDir(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function validateOperationalSemantics(options) {
+  const opts = options || {};
+  const skillsRoot = opts.skillsRoot;
+  const paths = Array.isArray(opts.manifest && opts.manifest.installed_paths) ? opts.manifest.installed_paths : [];
+  for (const p of paths) {
+    if (!isInsideDir(p, skillsRoot)) {
+      return { valid: false, reason: `installed path escapes platform root: ${p}` };
+    }
+  }
+  return { valid: true };
+}
+
+function copyInstalledHashes(records) {
+  if (!Array.isArray(records)) {
+    return [];
+  }
+  return records.map((r) => ({ target: r.target, sha256: r.sha256 }));
+}
+
+function atomicWriteFile(targetPath, content, options) {
+  const opts = options || {};
+  const basename = path.basename(targetPath);
+  const dir = path.dirname(targetPath);
+  const dirLabel = opts.dirLabel || 'atomic write dir';
+  const tempLabel = opts.tempLabel || 'atomic temp file';
+  const targetLabel = opts.targetLabel || 'atomic target file';
+  const flags =
+    fs.constants.O_WRONLY |
+    fs.constants.O_CREAT |
+    fs.constants.O_EXCL |
+    (fs.constants.O_NOFOLLOW || 0);
+  let tmp = null;
+  let fd = null;
+
+  assertSafePath(dir, dirLabel);
+  fs.mkdirSync(dir, { recursive: true });
+  assertSafePath(dir, dirLabel);
+
+  try {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_ATTEMPTS; attempt += 1) {
+      const suffix = crypto.randomBytes(8).toString('hex');
+      const candidate = path.join(dir, `.${basename}.tmp-${process.pid}-${suffix}`);
+      try {
+        assertSafePath(candidate, tempLabel, { allowNonDirectoryTarget: true });
+        fd = fs.openSync(candidate, flags, 0o666);
+        tmp = candidate;
+        break;
+      } catch (e) {
+        if (e && e.code === 'EEXIST') {
+          continue;
+        }
+        throw e;
+      }
+    }
+    if (fd === null || tmp === null) {
+      throw new Error(`unable to create exclusive temp file for ${targetPath}`);
+    }
+
+    fs.writeFileSync(fd, content);
+    fs.closeSync(fd);
+    fd = null;
+    assertSafePath(targetPath, targetLabel, { allowNonDirectoryTarget: true });
+    fs.renameSync(tmp, targetPath);
+    tmp = null;
+  } catch (e) {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (closeErr) {
+        /* best effort */
+      }
+    }
+    if (tmp !== null) {
+      try {
+        fs.rmSync(tmp, { force: true });
+      } catch (cleanupErr) {
+        /* best effort */
+      }
+    }
+    throw e;
+  }
+}
+
+function validate(manifest, options) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return false;
+  }
+  for (const f of REQUIRED_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(manifest, f)) {
+      return false;
+    }
+  }
+  if (manifest.schema_version !== SCHEMA_VERSION) {
+    return false;
+  }
+  if (typeof manifest.platform !== 'string' || manifest.platform.length === 0) {
+    return false;
+  }
+  const opts = options || {};
+  if (opts.expectedPlatform && manifest.platform !== opts.expectedPlatform) {
+    return false;
+  }
+  if (typeof manifest.version !== 'string') {
+    return false;
+  }
+  if (typeof manifest.installed_at !== 'string' || manifest.installed_at.length === 0) {
+    return false;
+  }
+  if (!Array.isArray(manifest.installed_paths)) {
+    return false;
+  }
+  for (const p of manifest.installed_paths) {
+    if (typeof p !== 'string' || p.length === 0) {
+      return false;
+    }
+  }
+  if (!Array.isArray(manifest.backups)) {
+    return false;
+  }
+  for (const b of manifest.backups) {
+    if (!b || typeof b !== 'object' || Array.isArray(b)) {
+      return false;
+    }
+    if (typeof b.target !== 'string' || typeof b.backup !== 'string') {
+      return false;
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(manifest, 'installed_hashes')) {
+    if (!Array.isArray(manifest.installed_hashes)) {
+      return false;
+    }
+    for (const h of manifest.installed_hashes) {
+      if (!h || typeof h !== 'object' || Array.isArray(h)) {
+        return false;
+      }
+      if (typeof h.target !== 'string' || !isSha256(h.sha256)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function create(platform, version, partial) {
+  const p = partial || {};
+  return {
+    schema_version: SCHEMA_VERSION,
+    platform,
+    version,
+    installed_at: p.installed_at || new Date().toISOString(),
+    installed_paths: Array.isArray(p.installed_paths) ? p.installed_paths.slice() : [],
+    backups: Array.isArray(p.backups) ? p.backups.map((b) => ({ target: b.target, backup: b.backup })) : [],
+    installed_hashes: copyInstalledHashes(p.installed_hashes),
+  };
+}
+
+function read(platform, options) {
+  const p = manifestPath(platform, options);
+  assertSafePath(path.dirname(p), 'manifest dir');
+  if (!fs.existsSync(p)) {
+    return null;
+  }
+  assertSafePath(p, 'manifest file', { allowNonDirectoryTarget: true });
+  const data = fs.readFileSync(p, 'utf8');
+  return JSON.parse(data);
+}
+
+function write(platform, manifest, options) {
+  const p = manifestPath(platform, options);
+  const dir = path.dirname(p);
+  assertSafePath(dir, 'manifest dir');
+  fs.mkdirSync(dir, { recursive: true });
+  assertSafePath(dir, 'manifest dir');
+  const payload = JSON.stringify(manifest, null, 2) + '\n';
+  atomicWriteFile(p, payload, {
+    dirLabel: 'manifest dir',
+    tempLabel: 'manifest temp file',
+    targetLabel: 'manifest file',
+  });
+  assertSafePath(p, 'manifest file', { allowNonDirectoryTarget: true });
+  return p;
+}
+
+function removeManifest(platform, options) {
+  const p = manifestPath(platform, options);
+  assertSafePath(p, 'manifest file', { allowNonDirectoryTarget: true });
+  fs.rmSync(p, { force: true });
+  return p;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  REQUIRED_FIELDS,
+  validate,
+  create,
+  read,
+  write,
+  manifestPath,
+  defaultXskRoot,
+  assertSafePath,
+  isSafePath,
+  isInsideDir,
+  validateOperationalSemantics,
+  atomicWriteFile,
+  removeManifest,
+};

package/lib/ownership.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// Ownership constants and per-skill safety predicates shared by install and
+// uninstall. Lives in its own module so install.js can run an uninstall-first
+// reset without requiring uninstall.js (which would create a require cycle).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { isSafePath, isInsideDir } = require('./manifest');
+
+const PACKAGE_NAME = '@xenonbyte/xsk';
+const MARKER = '.xsk-owned';
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch (e) {
+    return false;
+  }
+}
+
+function isExistingNonRegularFile(p) {
+  try {
+    return !fs.lstatSync(p).isFile();
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+function hasUnsafeSkillPath(skillDir, skillFile, markerFile) {
+  return (
+    !isSafePath(skillDir, 'skill dir') ||
+    !isSafePath(skillFile, 'skill file', { allowNonDirectoryTarget: true }) ||
+    !isSafePath(markerFile, 'marker file', { allowNonDirectoryTarget: true }) ||
+    isExistingNonRegularFile(skillFile) ||
+    isExistingNonRegularFile(markerFile)
+  );
+}
+
+function hasValidMarker(markerFile) {
+  try {
+    return fs.readFileSync(markerFile, 'utf8') === `${PACKAGE_NAME}\n`;
+  } catch (e) {
+    return false;
+  }
+}
+
+function safeBackupForSkill(backups, skillFile, xskRoot, platform, skillsRoot) {
+  const matches = backups.filter((b) => b.target === skillFile);
+  const backup = matches[0];
+  if (!backup) return { backup: null, unsafe: false, missing: false };
+  if (matches.length > 1) return { backup, unsafe: true, missing: false };
+
+  const expectedDir = path.join(xskRoot, 'install', 'backups', platform);
+  const backupPath = path.resolve(backup.backup);
+  if (!isInsideDir(path.resolve(backup.target), skillsRoot)) {
+    return { backup, unsafe: true, missing: false };
+  }
+  if (!isInsideDir(backupPath, expectedDir)) {
+    return { backup, unsafe: true, missing: false };
+  }
+  if (!isSafePath(expectedDir, 'backup dir') || !isSafePath(backupPath, 'backup file', { allowNonDirectoryTarget: true })) {
+    return { backup, unsafe: true, missing: false };
+  }
+  if (!fs.existsSync(backupPath)) {
+    return { backup, unsafe: false, missing: true };
+  }
+  const stat = fs.lstatSync(backupPath);
+  if (!stat.isFile()) {
+    return { backup, unsafe: true, missing: false };
+  }
+  return { backup, unsafe: false, missing: false };
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  MARKER,
+  isSymlink,
+  isExistingNonRegularFile,
+  hasUnsafeSkillPath,
+  hasValidMarker,
+  safeBackupForSkill,
+};

package/lib/skills.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const ALL_PLATFORMS = ['claude', 'codex', 'opencode', 'gemini'];
+
+const skills = [
+  {
+    name: 'xsk-think',
+    description:
+      'Plan before coding. Weigh options, surface ambiguities, and produce a decision-complete design, then stop for approval.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'think',
+  },
+  {
+    name: 'xsk-bypass-claude',
+    description:
+      'Set the current project to Claude Code bypass-permissions mode by writing .claude/settings.local.json. Claude only.',
+    platforms: ['claude'],
+    fragmentBase: 'bypass-claude',
+  },
+  {
+    name: 'xsk-skill-scaffold',
+    description:
+      'Bring an agent-skill project up to the xsk standard, or refuse if the target is not an agent-skill project.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'skill-scaffold',
+  },
+  {
+    name: 'xsk-write-req',
+    description:
+      'Turn plain-language needs into a grounded requirement document in requirements/, with a self-audit gate before it is finalized.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'write-req',
+  },
+  {
+    name: 'xsk-archive-req',
+    description:
+      'Archive the active requirement document into requirements/archive/ and leave zero active docs.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'archive-req',
+  },
+  {
+    name: 'xsk-check',
+    description:
+      'Review a code change before it ships. Check scope drift, enforce hard stops, gate findings on evidence, then verify and sign off. Distilled from Waza /check.',
+    platforms: ALL_PLATFORMS.slice(),
+    fragmentBase: 'check',
+  },
+];
+
+function forPlatform(platform) {
+  return skills.filter((s) => s.platforms.includes(platform));
+}
+
+function get(name) {
+  return skills.find((s) => s.name === name);
+}
+
+module.exports = { skills, forPlatform, get, ALL_PLATFORMS };

package/lib/status.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { read, validate, defaultXskRoot, isSafePath, isInsideDir, validateOperationalSemantics } = require('./manifest');
+const { ALL_PLATFORMS, MARKER, rootFor } = require('./install');
+
+const STATES = ['not-installed', 'ok', 'drift', 'invalid'];
+
+function expectedInstalledPathType(p) {
+  const base = path.basename(p);
+  if (base === 'SKILL.md' || base === MARKER) {
+    return 'file';
+  }
+  return 'directory';
+}
+
+function recordedPathEntries(manifest) {
+  const installed = Array.isArray(manifest.installed_paths)
+    ? manifest.installed_paths.map((p) => ({ path: p, expectedType: expectedInstalledPathType(p) }))
+    : [];
+  const backups = Array.isArray(manifest.backups)
+    ? manifest.backups.map((b) => ({ path: b.backup, target: b.target, expectedType: 'file', kind: 'backup' }))
+    : [];
+  return installed.concat(backups);
+}
+
+function recordedPaths(manifest) {
+  return recordedPathEntries(manifest).map((entry) => entry.path);
+}
+
+function pathType(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    if (stat.isFile()) return 'file';
+    if (stat.isDirectory()) return 'directory';
+    return 'other';
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return 'missing';
+    throw e;
+  }
+}
+
+function recordedPathHasDrift(entry, options) {
+  const opts = options || {};
+  const exists = opts.exists || ((p) => fs.existsSync(p));
+  const safe = opts.safe || (() => true);
+  const typeOf = opts.typeOf || null;
+  if (!safe(entry.path, entry)) return true;
+  if (!exists(entry.path, entry)) return true;
+  if (typeOf && typeOf(entry.path, entry) !== entry.expectedType) return true;
+  return false;
+}
+
+function missingRecordedPaths(manifest, options) {
+  const opts = options || {};
+  return recordedPathEntries(manifest)
+    .filter((entry) => recordedPathHasDrift(entry, opts))
+    .map((entry) => entry.path);
+}
+
+function statusOf(manifest, options) {
+  const opts = options || {};
+  if (!manifest) return 'not-installed';
+  if (!validate(manifest, { expectedPlatform: opts.expectedPlatform })) return 'invalid';
+  const exists = opts.exists || ((p) => fs.existsSync(p));
+  const safe = opts.safe || (() => true);
+  const typeOf = opts.typeOf || null;
+  const paths = recordedPaths(manifest);
+  if (paths.length === 0) return 'ok';
+  return missingRecordedPaths(manifest, { exists, safe, typeOf }).length === 0 ? 'ok' : 'drift';
+}
+
+function computeStatus(options) {
+  const opts = options || {};
+  const platforms = opts.platforms || ALL_PLATFORMS;
+  const xskRoot = opts.xskRoot || defaultXskRoot();
+
+  const result = { platforms: {} };
+  for (const platform of platforms) {
+    let manifest = null;
+    let readError = null;
+    try {
+      manifest = read(platform, { xskRoot });
+    } catch (e) {
+      readError = e;
+    }
+
+    if (readError) {
+      result.platforms[platform] = {
+        state: 'invalid',
+        reason: `manifest is not valid JSON: ${readError.message}`,
+      };
+      continue;
+    }
+
+    if (!manifest) {
+      result.platforms[platform] = { state: 'not-installed' };
+      continue;
+    }
+
+    let skillsRoot = null;
+    if (validate(manifest, { expectedPlatform: platform })) {
+      skillsRoot = rootFor(platform, opts.platformRoots);
+      const semantics = validateOperationalSemantics({ platform, skillsRoot, manifest });
+      if (!semantics.valid) {
+        result.platforms[platform] = { state: 'invalid', reason: semantics.reason };
+        continue;
+      }
+    }
+
+    const exists = (p) => fs.existsSync(p);
+    const backupRoot = path.join(xskRoot, 'install', 'backups', platform);
+    const safe = (p, entry) => isSafePath(p, 'status recorded path', {
+      allowNonDirectoryTarget: entry.expectedType !== 'directory',
+    }) && (
+      entry.kind !== 'backup' ||
+      (
+        isInsideDir(entry.target, skillsRoot) &&
+        isInsideDir(p, backupRoot) &&
+        isSafePath(backupRoot, 'status backup dir') &&
+        isSafePath(p, 'status backup file', { allowNonDirectoryTarget: true })
+      )
+    );
+    const state = statusOf(manifest, { expectedPlatform: platform, exists, safe, typeOf: pathType });
+    const entry = { state };
+    if (state === 'drift') {
+      entry.missing = missingRecordedPaths(manifest, { exists, safe, typeOf: pathType });
+    }
+    if (state === 'ok' || state === 'drift') {
+      entry.installedCount = (manifest.installed_paths || []).filter(
+        (p) => p.endsWith('SKILL.md'),
+      ).length;
+      entry.version = manifest.version;
+    }
+    result.platforms[platform] = entry;
+  }
+  return result;
+}
+
+function render(result, options) {
+  const opts = options || {};
+  if (opts.json) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  const order = opts.platforms || Object.keys(result.platforms);
+  for (const platform of order) {
+    const entry = result.platforms[platform];
+    if (!entry) continue;
+    let line = `${platform}: ${entry.state}`;
+    if (entry.installedCount !== undefined) {
+      line += ` (${entry.installedCount} skill${entry.installedCount === 1 ? '' : 's'})`;
+    }
+    if (entry.version) {
+      line += ` v${entry.version}`;
+    }
+    if (entry.missing && entry.missing.length) {
+      line += `; ${entry.missing.length} recorded path(s) missing`;
+    }
+    if (entry.reason) {
+      line += ` - ${entry.reason}`;
+    }
+    lines.push(line);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { statusOf, computeStatus, render, STATES };